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INTRODUCTION 


Logical address space in a task is composed of regions. 
There are three basic types of regions, task regions, static 
regions, and dynamic regions. Task regions, into which tasks are 
loaded, are created using information set up by the Task Builder. 
Static and dynamic regions are generally used to share code or 
data among several tasks. Static regions are created using the 
Task Builder; dynamic regions are created during task execution, 
using executive directives. 


This module discusses static regions. You can use these 
Static regions to: 


e Create memory areaS containing code which is shared among 
tasks 


e Create memory-resident data areas which can be used _ for 
communication between tasks or successive invocations of 
the same task 


e Communicate directly with a peripheral device through the 
T/O page. | 


OBJECTIVES 


1. To create and use a resident common region 
2. To create and use a resident library 


3. To determine whether a position independent or an absolute 
shared region should be used in a given situation 


4. To create and use a device common. 


RESOURCE 


e RSX-11M/M-PLUS Task Builder Manual, Chapter 5 
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TYPES OF STATIC REGIONS 


Static regions, also called shared regions, are areas of 
memory which are shared among tasks. They allow tasks to share 
data or code with very little overhead. Unlike send and_ receive 
directives, no executive directives are needed, and the area's 
size is limited only by virtual address and possibly physical 
memory limitations. The virtual addressing limit must be met for 
both the region itself and any tasks which use the region. For a 
task which uses the region, the total applies to all regions used 
plus the task's code. 


Static regions offer very quick access, since the area is 
loaded before the tasks which use it are run. Once loaded, it is 
available directly in memory. Therefore, it offers much faster 
access than disk-resident data. 


Table 7-1 summarizes the types of shared regions available on 
an RSX-11M system. A resident common contains data. The data can 
be accessed by several different tasks, each with read only access 
or with read/write access. 


A resident library contains reentrant subroutines, which can 
be called by several different tasks. A single copy of each 
Subroutine can be shared, thus reducing’ the total memory 
requirements of the tasks. The term resident is used because the 
shared region is task-built, installed, and loaded into memory 
separately from the tasks which access it. 


A third type of shared region is a device common, a_= special 
type of resident common. It occupies physical addresses on the 
I/O page, which correspond to I/0 device registers instead of 
physical memory. Therefore, this kind of common allows a task to 
reference an I/O device directly. Unlike other resident commons, 
a device common has no true contents because it has no physical 
memory associated with it. 
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Table 7-1 Types of Static Regions Available on RSX-11M 
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MEMORY ALLOCATION 


Memory is allocated independently to the shared region and to 
the individual tasks which use it. We will call the tasks which 
use the region referencing tasks. On an RSX-11M system, the 
shared region must reside in a dedicated common type partition. 
The name of the partition must be the same as the name of the 
region. The partition can be created at SYSGEN time or later by 
the system manager or a privileged user. Once the region is 
installed and loaded into the partition, it cannot be 
'checkpointed. 


MAPPING 


Shared regions can be written and task-built as_ either 
position independent regions or as absolute regions. On a mapped 
system, position independent regions can be placed anywhere in a 
referencing task's virtual address space. This means that the 
virtual addresses used to map to the region can correspond to any 
available APR. | 


Figure 7-1 shows a position independent region, POSIND, and 
three referencing tasks. ° The region is loaded into memory into 
the partition POSIND; the partition name must be the same as_- the 
name of the- region. Recall that a virtual address window for 
mapping must begin with a base address for an APR on a 4K_ word 
boundary. Because the region is 5K words in length and each APR 
can only map at most 4K words, two APRS are needed to map_ the 
region. 


Task A maps the shared region uSing APRS 6 and 7, starting at 
virtual address 149000(8). It could in fact use APRS 5 and 6, 
beginning at virtual address 1299@0(8) or APRS 4 and 5, beginning 
at virtual address 1@89000(8). 


Task B maps the shared region at the first available APR 
above the task code, using APRS 2 and 3, beginning at virtual 
address 49890(8). It could use APRS 3 and 4, 4 and 5, 5 and 6, or 
6 and 7 as well. 
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Task C maps the shared region using APRS 6 and 7, Starting 
with virtual address 149900(8). There is no other possible way 


for Task C to map the shared region because APR 6 is the first 
available APR. 


When you task-build a referencing task, you can specify which 
APR to use in mapping the region. If you do not specify an APR, 
the Task Builder selects the highest set of available APRs. When 
task A and task C were built, the user either did not specify an 


APR, or specified APR 6. When task B was built, the user 
specified APR 2. 
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An absolute shared region has its virtual addresses fixed 


when it is task-built. All tasks which reference it must use 
those virtual addresses, and the corresponding APRs, to map to the 
region. Figure 7-2 showS another region ABSOLU and_ three 


referencing tasks, A, B and C. The shared region ABSOLU was built 
to use virtual addresses 120000(8)-147777(8) (6K words) with APRs 
5 and 6. All referencing tasks must map to the region using these 
APRS. Therefore, task A and task B can both map to the region, 
Since APRS 5 and 6 are available. Task C, on the other hand, 
cannot reference ABSOLU, since APR 5 is already used by its task 
code. 


You may think that there is no reason to ever limit yourself 
by making a region absolute. However, there are code restrictions 
for position independent regions due to the fact that a_ shared 
region is task-built separately from any of its referencing tasks. 


When the region is task-built, all code within it is set. 
The code has to be written using special position independent 
coding techniques to allow it to be placed at possibly different 
virtual addresses in the various referencing tasks. This is only 
a problem for data if the data is not position independent; for 
example, a jump table. 


The starting virtual address of each routine, defined by its 
label, is assigned when the referencing task is task-built. This 
address may vary depending on which base APR is used to map_ the 
region. The address of a given routine may vary from one 
referencing task to another. But the address placed in the table 
itself was already fixed when the region was task-built, and does 
not change for each referencing task. Further, that address may 
not match any of the addresses assigned in referencing tasks. For 
example, consider the following jump table and routines W, X, and 
Y; 


JMPTAB: ~-WORD W 


eWORD X 
eWORD Y 
W: ‘ 
Xs . 
b <- : 
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Figure 7-2 Tasks Using an Absolute Shared Region 
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The addresses resulting from the .WORD directives) are fixed 
when the region is task-built; e.g., at W = 1590(8), X = 1549(B), 
and Y = 1626(8). If the referencing task places the actual 
addresses WwW, xX and Y at those virtual addresses, everything will 
work fine. But if it starts mapping at APR 4 (virtual address 
120000), the labels themselves will be assigned addresses 
120000(8) + 1500(8) = 121500(8), 120000(8) + 1540(8) = 1215408(8), 
and 120000(8) + 1626(8) = 121626(8). 


However, the values in the table are already set at 15980(8), 
1540(8), and 1626(8), and they no longer address the correct 
locations. A jump or call by way of the table to routine W will 
result ina transfer to location 15@9(8) in the referencing task, 
and definitely not to routine W. To avoid this problem, jump 
tables should be included in the referencing task code instead of 
in the shared region. 


Instructions in shared regions are even trickier to program. 
All references which are relative to the current PC, for example, 
eight bytes from here, work fine. But a reference to an actual 
virtual address, for example, virtual address 42690(8) or @#A, only 
works if 4269(8) or A remains set at that virtual address. For a 
discussion of position independent code and how to write it, see 
Appendix H of the IAS/RSX-11 MACRO-11 Reference Manual. 


All of this means that in general, the decision about whether 
to create a position independent or an absolute shared region is 
based on the code restrictions, rather than the flexibility. In 
general, resident commons, containing data, are created position 
independent; and resident libraries, containing code, are created 
absolute. 


Figure 7-3 shows the program development process for creating 
a shared region and a referencing task. Specific steps for each 
process are discussed later in this module. Assemble and 
task-build the shared region separate from the referencing task, 
and before task-building the referencing task. 


Since it is not an executable task, certain. task—build 
Switches are used to create a task image with no header and no 
stack. An additional file, called a symbol definition file, is 
also. created at task—-build time. This file contains information 
about the symbols defined in the region, which the Task Builder 
will use when it builds the referencing task to set up linkage to 
the region. 
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After task-building the shared region, task-build the 
referencing task. It can be written and assembled earlier, if 
desired. The name of the region is specified to the Task Builder 
so that it can access the symbol definition file and set up the 
linkage to the shared region. The shared region must be installed 
(causing it to be loaded into memory as well) before any 
referencing task is run, 


REFERENCES TO A SHARED REGION 


The following kinds of references are made to a shared region 
by a referencing task: 


e The task retrieves data from, or stores data in, a 
resident common. 


e The task calls or jumps to a routine in ae resident 
library. 
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Figure 7-3 Program Development for Shared Regions 
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Techniques of Referencing 


When you write the code for the shared region and_ the 
referencing task, you must pick a technique to resolve the 
references to the shared region. Some of the techniques are _ the 

Same as the ones we used in Chapter 6 for referencing data in the 
‘ root from an overlay segment. 


Using Overlaid Psects (Data Only) 


This technique is similar to the one for overlays. An 
example appears below. This time the Overlaid (OVR) Psect is 
defined in the shared region, then the same Psect is specified in 
the referencing tasks. The Task Builder, as usual, combines the 
different occurrences of each Psect. Because the shared region is 
built first, the Psect MYDATA is placed there. Later, when the 
referencing task is built, the new occurrence of MYDATA is 
combined with the one in the shared region. The OVR attribute 
tells the Task Builder to start the allocation at the same 
location as the allocation already there, causing the addresses to 
be overlaid. This, in effect, just sets up the addressing so that 
M references the first word of the region, the 3. 


Shared region: 
- PSECT MYDATA D,GBL,OVR ; Defaults: REL,RW 
~WORD od gal S-™ O% 
- END 


Referencing task: 


- PSECT MYDATA D,GBL,OVR PSECT in shared 


me tO 


region 
M=, ; Addr of start of region 
- PSECT ; Back to blank Psect 
START: CMP M,#5 Check value 


BGT FIFTY Branch if greater 
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Using Global Symbols (Data or Subroutines) 


This technique is also the same as the one used in overlays. 
An example for data and for a subroutine appear below. In both 
cases, the label or labels are defined as global symbols. The 
referencing task uses the same global symbols to access the data 
or to call the subroutine. The possibly needed Psect name will be 
discussed later in the module. 


For Data 
Shared region: 


Possibly needed Psect name 
»=PSECT Z2ZZ 


=e we 


Ms: -WORD 3.74. ; Define data and symbols 
Ns - WORD 5. 
- END 


Referencing task: 
CMP M,#5 : Check value 
BGT FIFTY ; Branch if greater 
For Subroutine Names 
| Shared region: 
: Subroutine 


AADD: : 


RETURN : Return 


Referencing task: 
; Set up arguments 


CALL AADD ; Call subroutine 
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Using Virtual Addresses (Data Only) 


This technique is not available with overlays. If the shared 
region is built absolute, the starting virtual address of the 
region is fixed when the region is task-—-built. In the example 
below, it iS assumed that the region is task-built absolute to 
begin at virtual address 16@0@0(8). The referencing task can 
access the data by using the actual virtual address where the data 
is mapped. 


If the region is built position independent, it can be mapped 
at a specific base virtual address (or base APR) by specifying a 
base APR in the task-build command for the referencing task. In 
this example, specifying APR 7 would set the base virtual address 
for the region at 169990(8). 


Shared region: 


Possibly needed Psect name 
~-PSECT ZZZ 
- WORD 3.740756 
- END 


me Me 


Referencing task: 
Shared region must be task-built either: 
absolute starting at V.A. 1690000 
position independent and referencing task is 


task-built to force region to Start at 
V.A. 160000 


=e ™e Se MO MO Ne NE 


M = 160000 ; Addr of start of region 
CMP M,#5 ; Check value 
BGT FIFTY ; Branch if greater 
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Table 7-2 summarizes the techniques for referencing a_ shared 
region. When you task-build the shared region, you can specify 
whether or not you want the Psect names placed in the _ symbol 
definition file (.STB file). They must be there if you use the 
technique of overlaid Psects to reference the region. Use the 
/SHAREABLE:COMMON qualifier (/CO in MCR) to include the. Psect 
names. 


If global symbols or virtual addresses are used, it is best 
to exclude the Psect names in the .STB file. Use the 
/SHAREABLE: LIBRARY qualifier (/LI in MCR) to exclude Psect names. 
This avoids possible task-build errors due to Psect conflicts. 


If Psect names are kept in the .STB file, each Psect defined 
in the region, including the default blank (. BLK.) Psect is 
there. The Task Builder tries to collect allocations together if 
a matching Psect name appears in the referencing task. However, 
it can't add to the allocation in the region, since the region is 
already built. Therefore, if the Psect results in additional 
allocation to the Psect (always true if the Psect has_ the 
concatenate (CON) attribute), then a task-build error "LOAD 
ADDRESS OUT OF BOUNDS" results. This is because the new 
allocation can't be added to the already built shared region. 


Therefore, if Psect names are placed in the .STB file, the 
Psect names in the referencing task must not match any in the 
shared region, including the default blank Psect. Avoiding this 
is especially difficult if the shared region is a system resident 
library like FCSRES or FORRES, which was written by DIGITAL. In 
this case, you may not know what Psect names were used in the 
original source code. 


AS a general rule, place Psect names in the .STB file only if 
you use overlaid Psects to reference the region. Table 7-3 shows 
the interaction of three task-builder switches or qualifiers. 
They are; /CODE:PIC, for position independent or not; 
/SHAREABLE:COMMON, for placing Psect names in the .STB file; and 
/SHAREABLE: LIBRARY, for not placing Psect names in the .STB file. 


The name COMMON is used for keeping Psect names because 
overlaid pPsects can only be used for data references, therefore 
they are generally used in resident commons. The name LIBRARY is 
used for not keeping Psect names because global symbols are 
generally used to reference subroutines in a resident library. In 
fact, if a resident common is referenced using global symbols or 
virtual addresses, it is also built /SHAREABLE:LIBRARY to avoid 
Psect conflicts. 
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Table 7-2 Techniques of Referencing a Shared Region 
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PROCEDURE FOR CREATING SHARED REGIONS AND REFERENCING TASKS 


Creating a Resident Common or Resident Library 


1. Code your shared region. 
e Set up for an appropriate referencing technique. 


- Choose either overlaid Psects, global symbols, or 
virtual addresses for a resident common. 


- Use global symbols for a resident library. 
e Choose position independent or absolute. 


- The decision is based mainly on _ the coding 
techniques used. 


- If the code is_ position independent, build 
position independent (typical for resident 
common). 


- If the code is not position independent, build 
absolute (typical for resident library). 


e Resident common - reserve space, plus you may 
Initialize locations. 


e Resident library - code must be reentrant. See the 
section on Reentrancy in Chapter 5 of the PDP-11 
Processor Handbook for more information about 


reentrant code. 
2. Assemble the shared region. 
3. If not already done, create the common type partition. 
@e Name must be the same as the name of the region. 
e Best done when the system is SYSGENed. 


@e Use the SET PARTITION (SET/MAIN in MCR) command. to 
Create a partition. 


@e Use the SET NOPARTITION (SET/NOMAIN in MCR) command to 
eliminate a partition. 
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e Examples: 


>SET PARTITION:MYCOM/BASE:7114/SIZE: 200- 
-> /COMMON 


Creates the common type partition MYCOM with base 
physical address 7114@0(8) and size 29990(8) bytes. 
No other partition may use this space at the same 
time. 

>SET NOPARTITION:MYCOM 

Eliminates the partition MYCOM. 


NOTE 
Before you create or eliminate any 
partitions on your system, check with 
your system manager to find out what 
area of memory you may use. 


4. Task-build the shared region. 
e Symbol definition file (.STB) required. 


e Build position independent or absolute (see Table 
7-3) ° 


e Keep or do not keep Psect names (see Table 7-3). 
e Use required switches and options (see Table 7-4). 


5. Install the shared region in the common type partition 
before running any referencing task. 


@e Not required before task-building the referencing 
tasks. 


e Use the INSTALL (INS in MCR) command to install the 
region. 


-~ This command also loads the region into memory. 
This is unlike an executable task, which is 
usually loaded into memory only when it is 
activated. 


398 


STATIC REGIONS 


e There is no command to remove a region. It is removed 
by either installing another region or eliminating the 
partition. . 


The required switches and options in Table 7-4 are needed for 
different reasons. No header or stack is needed because this is 
not an executable task. The referencing tasks each have their own 
header and stack. The symbol table definition file is needed to 
allow the Task Builder to link referencing tasks to the region. 
The partition name specifies the partition into which the region 
will be loaded. 


For an absolute region you must specify a base address. If 
you specify a nonzero length, the specified value is usSed as a 
maximum length. A task-builder error results if the length of the 
region is longer than the length specified. If you specify a 
length of zero, the region is set up with the size needed for’ the 
code, aS long as it doesn't exceed the 32K word virtual addressing 
limit. 


Table 7-4 Required Switches and Options for Building 
a Shared Region 
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Example 7-1 has the source code for a resident common COMWP 


and a 


referencing task COMGP. Overlaid Psects are used for 


referencing the region. The following procedure is used to create 
the resident common. 


4 


Code the shared region. 


See COMWP.MAC in Example 7-1. The following notes are 
keyed to the example. 


@ The code is placed in an OVR Psect named MYDATA. This 
Same Psect is used in the referencing task. 


@ this series of assembler directives is equivalent to 
128 (18) -WORD 3 assembler directives. It initializes 
the first 128(18) words in the region to 3. 


@ this series of assembler directives initializes the 
next 128(1@) words in the region to 6. 


Assemble the shared region. 
>MACRO/LIST COMWP 
If necessary, create the common type partition. 


We will make a partition COMWP, eight blocks = 1989(8) 
bytes long. If the partition TSTPAR already exists on 
your system, you may be able to eliminate it and then set 
up your partition. Be sure to check with your system 
manager before doing this and also be sure to put MTSTPAR 
back when you are finished. 


! Check current partitions on the system 

>SHOW PARTITIONS 

!Record base address and length of TSTPAR and the type 
!of partition. Convert the values to blocks by 
!dropping the last two zeroes. (For example, 
!base address 12349@(8) = 1234 blocks, 

t!length = 280980(8) bytes = 200@(8) blocks) 

! Eliminate the partition TSTPAR 

>SET NOPARTITION: TSTPAR 

! Create the partition COMWP 

>SET PARTITION: COMWP/BASE: 1234/SIZE:1@/COMMON 

! Check to see if this worked correctly 

>SHOW PARTITIONS 
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Later, to eliminate the partition and to replace MTSTPAR, 
use the commands: ; 


>SET NOPARTITION:COMWP 
>SET PARTITION: TSTPAR/ BASE: 1234/SIZE:200/TASK 


Task-build the shared region. 
To build position independent: 


>LINK/OPTIONS/MAP/SHAREABLE:COMMON/NOHEADER - 
->/SYMBOL_TABLE/CODE: PIC COMWP 

Option? STACK=9 

Option? PAR=COMWP 

Option? <RET> 


The /OPTIONS switch allows you to enter options. /MAP 
indicates that you want amap file. /SHAREABLE: COMMON 
indicates that Psect names are to be placed in the .STB 
file (required to reference the shared region using 
overlaid Psects). /NOHEADER means do not include ae task 
header in the task image because this is not an executable 
task. /SYMBOL TABLE means make a .STB file (COMWP.STB). 
/CODE:PIC means poSition independent code for a position 
independent region. STACK = @ means no stack space is 
needed because this iS not an executable task. PAR = 
COMWP means the partition is COMWP. The Task Builder gets 
the length (for a maximum check) from the partition on the 
system. 


To build absolute: 


>LINK/OPTIONS/MAP/SHAREABLE:COMMON/NOHEADER - 
->/SYMBOL TABLE COMWP 

Option? STACK=@ 

Option? PAR=COMWP: 169000: 20000 

Option? <RET> 


Only changes: 
1. Omit /CODE:PIC. 


2. Specify a base virtual address and a maximum 
length. The base virtual address must correspond 
to a base virtual address for an APR (e.g., 2, 
200080(8), A4GGOB(8), 60000(8), 188000(8), 
120009(8), 149900(8), or 1690900(8)). The APRs 
used must be available in all referencing tasks. 
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5. Install the region. 
>INSTALL COMWP 
Installs the region and also loads it into memory. 


Note that this is different from an executable task, 
which usually isn't loaded until it is requested. 
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*TITLE COMWF 
+IDENT /0O1/ 
*eENABL LC 9 


+ 


File COMWF.MAC 


which creates and initia 
using oO 


Frogram 
which will be referenced 


Must ain 
STACK=0 
May he /C 


Task-build instructions? 
and /NOHEAIIER switchess 
Must create .STE file. 
(default). 


“Se Se SP Sh Sh Kh GP Sem “rp “E> “Sr E> “EP 


The code is Frlaced in @ Fsect na 
eFSECT MYDATA TiyGBL»sOVUR ¢ 
+REFPT 128. ; 
+WORT! 3. ; 
oENTIR 3 
+REPT 128, 3 
+»-WORTD &. $ 
+ENTIR 5 
+ENTI 
»TITLE COMGF 
»IQENT /01/7 
*+ENABL LC ; 

+ 


FILE COMGF.MAC 

resion COMWF. It uses the techni 
to reference the resion. 
Task-npuild instructions? 


>LINK/MAF/OP TION COMGF 
Ortion? RESCOM=COMWF/RO 


> > > Se ep Ke Wh > SP “er “> “ed “Eb 


Ortion? <RETS 
*+MCALL QIOWSSsEXIT#&S 3 
«FSECT MYRATA DveGBLy»sOVR & 
M=, 3 
; 
»FP SECT ; 
TOSE? »>BLAKW 2 3 
ARG? +BLAKW 1 ; 
; 
BUFF? +» BLAKE 100. ; 
FMT3 *ASCIZ /ZEI/ 3 
3 
FERRI? *ASCIZ /NIR ERROR ON QIO, 
1 
FERR2 3 *+ASCIZ 'T/0 ERROR ON QIO. 
$ 
7-1 Resident Common Referenc 
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313. 


Enable lower case 


lizes & common resion 


verlaid Faeects,. 


clude /SHAREABLE? COMMON 
and FPAR=COMWF ortions. 
QNEtFiC or aghsolute 


med MYDATA 


Nefaults REL sRW 
Rereat count 
Word value of 3, 
End rereat rance 
Rereat count 
Word value of 6. 
End rereat ranse 


Enable lower case 


This task sets the values from the static common 


aue of overlaid Fsects 


System macros 
Fsecet used im COMWF 


local symbol for start 
of resion 
Back to blank Foeect 


I/O status block 
Argument block for 
error code 

OQuteut buffer 
Format string for 
outeut of date 


NSW = Zl/ ¢ Directive 

error messase 

CODE = 420! ¢ I/O error 
mnessadte 


ed With Overlaid Psects 
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32 
33 N=32. § Looe count ~ 32. linesys 
34 § 8 #5 ver line 
30 +EVEN 
36 3 

3) 37 START? MOV #MyR2 § Starting addr of data 
38 § in the resion 
39 MOV #Ny RS * Loor count 
40 LOOF? MOV BUFF ¥ RO § Quteut buffer 
4l MOV #FMTyRI y Format string 
42 CALL $ENMSG + Edit message 

4 | 43 QIOWS$S #IOWVR ys toy tls +t LOSRs » SRUFF oR 1 F402 
44 RCS ERROR § Check for dir error 
45 TSTE IOSE + Check for I/0 error 
46 BLT ERROR1 § Branch on I/0 error 
47 ’ Stay here for sood write 
48 SOR RS»LOOF § Decrement counters looar 
49 > back if not vet done 
50 EXIT&S > Exit 
oi s Error code 
Se ERROR? MOV $lISWs ARG § Move SW to ars block 
33 MOV #FERRI» RI + Addr of format string 
34 BR SETUP + Branch to $E0UMSG code 
35 ERROR1? MOVE IOSEsrRO § Extend sign on I/70 
u6 MOV RO» ARG + Status and elace in 
o7 > ars block 
38 MOV #FERR2eR1 ¢$ Addr of format string 
UF SETUF2 MOV #BUFF » RO ¢ Addr of outeut buffer 
60 MOV #ARG eR2 § Addr of argument block 
61 CALL $ENMSG ’ Edit message 
62 , QTOWSS #IOWVBs #5 otto sey cEBUPF eRe #40> § Write 
63 $ message 
64 EXIT#SS § Exit 
65 +ENT! START 


Example 7-1 Resident Common Referenced With Overlaid Psects 
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Rum Session 


>INS COMUF 

>RUN COMGF 

3 3 3 3 3 3 3 3 

3 3 3 3 3 3 3 3 

3 3 3 3 3 3 3 3 

é é é é é 6 é é 

6 é é é é 6 é é 
é 6 é é 6 é é 


ry 
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Resident Common Referenced With OQOverlaid Psects 
(Sheet 3 of 3) 


Creating a Referencing Task 


5 ae Code 


the task, using’ the corresponding referencing 


technique, 


If Psect names are kept in the .STB file of the 
referencing task, avoid Psect conflicts. 


2. Assemble the task. 


3. Task-build the task. 


Specify shared regions using one of the _ following 
options: 


COMMON=common name for a system resident common 
(.STB and .TSK files must be in LB:[1,1]). 


LIBR=common name for a system resident library 
(.STB and .TSK files must be in LB:[1,1]). 
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RESCOM=common name for a user resident common 
(.STB and .TSK files in any device and any UFD 
using normal defaults). 


RESLIB=common name for a user resident library 
(any device and any UFD uSing normal defaults). 


e Append :RO if read-only access is desired. 
:RW if read-write access is desired. 
use "/" instead of ":" for RESCOM and RESLIB. 


e Only if the shared region is position independent, can 
you specify the base APR to be used to map the region. 
If not specified, the highest available APR or set of 
APRS is used, as needed. 


4. After installing the shared region, install and/or run the 
task. 


If the shared region is to be a system shared region, the 
-STB file and the .TSK file should be placed in LB:[1,1]. 
Otherwise, they can reside on any device under any UFD, as long as 
both files are in the same UFD on the same device. 


Read-only or read/write access affects the way the access 
bits in the page descriptor registers (PDRS) in the APRS are set 
up. A memory protect violation occurs if a task attempts to write 
to a region when it has read-only access. 
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COMGP.MAC in Example 7-1 contains the source code for a_ task 
to reference the shared region COMWP. Use the following procedure 
to create the task. : 


1. 


Code the task. 


See COMGP.MAC in Example 7-1. The following notes are 
keyed to the example. 


The same Psect, MYDATA, is used here aS in COMWP.MAC 
to set up referencing. M marks the beginning of the 
region. No initialization of the Ppsect can be 
performed in the referencing task. 


The main code is in the blank (. BLK.) Psect. 
Move the starting address of the region to R2. 
We use SEDMSG to set up each line of the display. We 
loop through once for each line, editing and 


displaying the values. 


The format string for SEDMSG. $%8D means convert eight 
words to signed decimal, with a tab between values. 


Assemble the task. 


Task-—build the task. 


>LINK/OPTION/MAP COMGP 
Option? RESCOM = COMWP/RO 
Option? <RET> 


Link task to resident common COMWP. COMWP.TSK and 
CONWP.STB are in the current UFD on SY:. Set up 
read-only access. Use the highest available APR, APR 
7, if the region was built position independent. 


After installing the shared region, install and/or run the 
task. 


To do a temporary install, run, remove: 


>RUN COMGP 


To install and then run: 


>INSTALL COMGP 
>RUN COMGP 
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Deciding whether read-only or read/write access to a_e region 
is required is usually straightforward. If a task moves data into 
the region or changes a value in the region, read-write access is 
required. If a task moves data out of the region or just reads 
values in the region, just read-only access is required. 


However, when QIOs are issued and the buffer is in the shared 
region, things get a little tricky. Obviously, to do a read 
(e.g., from a terminal) into a buffer in the shared region 
requires write access. A write (e.g., to a terminal) from a 
buffer in the region should only require read access. However, 
because the Executive is designed for very fast, real-time 
applications, it does not check the function code for a _ QIOo 
directive to see whether it is a read or a write. Instead it 
assumes the worst case - that all QIOS involving a buffer in a 
shared region are reads (from a peripheral device) into a buffer 
in the region, and that therefore, all QIOS require read/write 
access, This condition causes an I/O error (IE.SPR) for illegal 
user buffer. This condition does not affect Example 7-1 because 
SEDMSG creates the output string in a buffer within the 
referencing task area, and the QIOs do the writes from the 
referencing task area. 


In an example in a later module, you will see this’ problem 
come up. One solution is to get read/write access to the shared 
region. Another solution is to move the data from the shared 
region to a buffer in the referencing task area, and then use that 
buffer for the QIOs. A third solution is to build the task as a 
privileged task. 


Privileged tasks, similar to privileged terminals, are 
granted certain extra access to the system which nonprivileged 
tasks don't have. Some privileged tasks just gain these extra 
access rights, others map to the Executive as well. Normally, the 
Task Builder builds a task as a nonprivileged task. For a 
discussion of privileged tasks and how to task-build them, see 
Appendix D. 
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Example 7-2 shows a shared region (COMNP.MAC) and a 
referencing task (COMGGS.MAC) using global symbols to reference 
the shared region. Other than the difference in referencing 
technique, Example 7-2 is the same as Example 7-1. The following 
notes are keyed to the example. 


@ Because the region is built with the /SHAREABLE: LIBRARY 
switch, any Psect names used in the file are not placed in 
the .STB file. Therefore, the code for the referencing 
task can be placed in the default blank (. BLK.) Psect or 
any other Psect. If the library were instead built 
/SHAREABLE:COMMON, the Psect names used in the shared 
region would all be placed in the .STB file. In that 
case, using any Psect in the referencing task which is 
also used in the shared region would cause a Psect 
conflict, cauSing a LOAD ADDRESS OUT OF BOUNDS 
task-builder error. | 


6 The global symbol K marks the beginning of the_ shared 
region. 


The rest of the code is the same as COMWP.MAC in Example 
7-1 e 


ra Just use the global symbol K to reference the start of the 
Shared region. The Task Builder sets up the linkage to K, 
as it is defined in the shared region COMNP. The rest of 
the code is the same as that in COMGP.MAC in Example 7-l. 


The tape supplied with this course also contains an example 
uSing virtual addresses as a referencing technique. The shared 
region is still COMNP, the same one as in Example 7-2. The 
referencing task code is in the file COMGVA.MAC. It should be in 
 UFD [2@2,3] on your system. Check with your course administrator 
if you need help locating this example. 
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1 +TITLE COMNF 
2 +IDENT /0O17 
3 *+ENABL LC § Enable lower case 
4 3+ 
3 + File COMNF.MAC 
é 3 
7 + Frogram which creates and initializes 3 common resgiori 
8 3 which will be referenced using slohal symbols or 
9 § actual virtual addresses. 
10 3 
11 > Task-build instuctions? Must include /SHAREABLEJLIBRARY 
12 > amd /SNOHEADER switechess STACK=0 anc FAR=COMNF ortions. 
13 > Must create a .STEK file. May be /COMESPIC aor absolute 
14 § (the default>. 
15 3 
16 § This frosram elaces the code in the default blank 
@ 17 > ¢. BLK.) Psect. It could be in any Psect. FPsect 
18 s conflicts are avoided by using the /SHAREABLES LIBRARY 
19 § Switch om the task builder. 
20 3 
ei § Tefine Ky a slohal symbol 
@ 22 Kes eREFT 128. y Rereat count 
23 »WORT Se § Word value of 3. 
24 +ENDR + End rereat range 
© 20 «REPT 128. §’ Rereat count 
26 +WORTD &s * Word value of 6. 
27 +ENDR s End rereat ranse 
28 +ENT 


*TITLE COMGGS 


2 +IQENT /01/7 

3 *ENABL LC y Enable lower case 
4 3+ 

Ka ’ FILE COMGGS.MAC 

6 3 

7? * This task sets the values from the static common 
8 § resion COMNF. It uses a global symbol to reference 
v4 s the resion. 

10 3 

11 § Task-huild notes? 

12 ; 

13 ; LINK/MAF/OFTION COMGGS 

14 3 Ortion? RESCOM=COMNF/RO 

1S r) Qetion? <RET> 

16 3~ 


17 «¢MCALL QIOWSS + EXITSS y External system macros 


Example 7-2 Resident Common Referenced With Global Symbols 
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y 
19 IOSE? +RLAW a + 70 status block 
20 ARG? e BLAW 1 y Arsument block for 
21 > error code 
22 RUFF ? » BLAKE 100. > Quteut buffer 
23 FMT? *ASCIZ /2Z80/ y Format strings for 
24 > onutreut of data 
25 FERRit .ASCIZ /DIR ERROR ON QIO. DSW = Z0D/ ¢ Directive 
26 $ error message 
27 FERR2$ .ASCIZ $!I/0 ERROR ON QIO. COME = xn! ¢ T/0 
28 > error messade 
29 N=32. + Looe count - 32. lines» 
30 > 8 #8 rer line 
31 +EVEN . 
32 START? MOV thKeR2 + Starting addrress of 
33 $ data in the region 
34 MOV #NeRS > Loor count 
35 L.OOF 3 MOV #BUFF » RO § Quteut buffer 
36 MOV $F MT» RL § Format string 
37 CALL $E0MSG > Edit message 
38 QIOWSS #10.,WVBy t5e¢19 7k ITOSKs » S#RUFF se R1 y $40> 
39 RCS ERROR 5 Check for dir error 
40 TSTE IOSE + Check for I/0 error 
4i BLT ERROR § Branch an I/0 error 
42 y Stay here for good write 
43 SOR RS »¥LOOF > Decrement counters loor 
44 y back if not vet done 
4S EXITS g Exit 
44 s Error code 
47 ERROR? MOV $0SWs ARG > Move I0ISW to ars block 
48 MOV #FERRI s RA > Addr of format strings 
49 BR SETUF > Branch to $E0MSG code 
50 ERRORI? MOVE IOSEsRO >’ Extend sigm om I/0 
a MOV RO» ARG > Status and rlace in 
32 y are block 
53 MOV #FERR2sR1 + Addr of format strings 
54 SETUF3 MOV # BUFF » RO s Addr of outrut buffer 
33 MOV #ARGyR2 ’ Addr of argument block 
56 CALL $EDNMSG s Edit messade 
37 QIOWSS #10. .WVBy t5e#1l see ckBUF Fo R1y#40> & Write 
98 5 error messade 
9 EXIT#S § Exit 
60 +END START 


Example 7-2 Resident Common Referenced With Global Symbols 
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Rum Session 


“INS COMNF 

“RUN COMGGS 

3 3 3 3 3 3 3 3 
3 3 3 3 3 3 3 3 
3 3 3 3 3 3 3 3 
& é é & 6 & & & 
& & é 6 6 & & & 


6 & é & 6 & & & 


Example 7-2 Resident Common Referenced With Global Symbols 
(Sheet 3 of 3) 


Example 7-3 contains a shared library, LIB.MAC, and a 
referencing task, USELIB.MAC. The shared library contains four 
Simple arithmetic routines to add, subtract, multiply, and divide 
two numbers. They are all written to be reentrant, plus they can 
be called from a FORTRAN program with a_ standard FORTRAN 
subroutine Cali. Basically, this means that on entry the 
arguments are assumed to be set up as follows: 


R5 
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For additional information on the FORTRAN/MACRO-11 interface, 
see Appendix C. Each subroutine saves and restores all of the 
registers, using the system library routine SSAVAL. The 
referencing task, USELIB, calls each of the subroutines once, 
uSing the operands 8(1@) and 2(18), and displays just the answers 
for the four operations. The following notes are keyed to Example 
T= 2% 


@ Each subroutine entry point is defined with a global 
symbol. 


@ Each subroutine is in a Psect of the same name as_ the 
subroutine. In fact, the Psects are optional since the 
library is built /SHAREABLE: LIBRARY. The specified Psect 
names are not placed in the .STB file. 


(3 For AADD and SUBB, move the first operand to RQ@, perform 
the operation in R@, then move the answer to the third 
operand for return to the caller. 


@ For MULL, uSe Rl instead of RG, so that the product is 
limited to just Rl (16 bits). If R@ were used instead, a 
32-bit product is returned (low-order 16 bits in Rl, 
high-order 16 bits in RQ@). 


@ For DIvv, a 32-bit dividend is assumed in Rn and Rn+l, so 
here it is R2 and R3 (low-order 16 bits in R3, high-order 
16 bits in R2). Therefore, the 16-bit operand is placed 
in R3 and the high-order word is cleared. The 16-bit 
quotient, returned in R2, is then moved into the third 
operand for return to the caller. 


The two operands. 


Space allocated for return of the result. 


FORTRAN type argument block is built on the stack, in 
reverse order, so that SP points to the start of the 
block. 


9 | The address in SP is moved to R5, so R5 points to the 
start of the argument block. 


@ call each of the routines. Since R5 and the stack are not 
disturbed between calls, the same argument block can be 
used for all four calls. 


@ call the subroutine PRINT to edit the output message and 
display it for all operations. 
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Example 7-3 Shared Library 


AALL » 


eTITLE 
IDENT 
«ENABL 


File LIB.MAC 


This file contains 
MULL. » 
arrrorriate inteser oreration. 


SUBE » 


Calling convention? 


Task-build instructions? 
and /NOHEADTER switchess 
Must create 
(default). 
conflicts. 


oP SECT 
CALL. 
MOV 
ADIN 
MOV 
RETURN 


eFSECT 
CALL 
MOV 
SUB 
MOV 
RETURN 


+P SECT 
CALL 
MOV 
MUL. 


MOV 
RETURN 


«FSECT 
CALL 
MOV 
CLR 
NIV 
MOV | 
RETURN 
«END 


Usins /SHARE ABLES LIBRARY 
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LIE 
/O1/ 


LC 5 Enaeble lower case 


the FORTRAN callable subroutines 
and DIVVy which eerform the 


CALL sub Corlysore2s ans) 

Must inelucde /SHAREABLES LIBRARY 
STACK=0 and FAR=LIB ortions, 

Maw be /CONMEIFPIC or absolute 
avoids Fsect 


AAITyROs ITyGBRLy REL » CON 

$SAVAL Save a1] resisters 
@2¢RS) RO Move ist orerancd 

C4 CRS)» RO Add 2nd orerand 
RO»@6¢(RS) Store result 

Restore ress and return 


“<=> 


Sh “> “Gr “GP 


SUBBRyROsT»GBRL»y REL »yCON 
$€SAVAL 5 Save all resisters 


C2(RS) ekO + Move ist orerand 
@C4¢(RS) RO + Subtract 2nd orerand 
ROs@6 (RS) ¢ Store result 

’ Restore ress and return 


MULL »ROs I eGBLyREL » CON 
$SAVAL Save ell resisters 
@2CR5) Ri Move ist orerand 

C4( RS) R1 Multirly (Canswer in 
Just RI? 

Store result 
Restore ress 


“<e> 


R1v@6CRS) 


“<> “> “Gr *@> SDP 


and return 


NIVVUeROs Ty GRLy REL » CON 


$SAVAL + Save all resisters 
G2(RS) »RZ § Move ist orerand 
R2 § Clear hish order 16 bits 
C4( RS) »R2 + Tlivide 
R229@46(RS> + Store result 

§ Restore ress and return 


(Sheet 1 of 2) 
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SHOUT es RL v #402 3 


Enable lower case 


System macros 
Orerand 1 
OQeerand 2 
Result 


Outeut buffer 


¢ Format string 
the 


For result 
Orerand 2 


stack 


Orerand 1 

Number of arguments 
RSs > ars block 
Add orerands 
Frint results 
Subtract orerands 
Frint results 
Multirely orerands 
Frint results 
Nivide orerands 
Frint results 

Hit 


the oreration 


Set ur for $E0MSG 


Edit message 

Write 
MEeSsagte 

Return 


STATIC REGIONS 
1 sTITLE USELIB 
2 IDENT /01/ 
3 s-ENABL LC ; 
4 $+ 
5 § File USELIB.MAC 
6 3 
7 § MACRO-11 task to use the resident library LIB 
8 3 
9 § Task-hbuild instructions? 
10, 3 
141i 3 >LINK/MAP/OPTION USELIB 
120 3 Ortion? RESLIB=LIB/RO 
13 3 Ortion? <RET> 
14 $- 
15 »MCALL QIOWSSYEXITSS = 3 
16 
O| ¢ OF 1! -WORD 8, 3 
18 OF2? WORD 2 ; 
19 ANS? -BLKW 4 ; 
20 
21 out? +BLKW = 100. ; 
22 FORMAT! .ASCIZ /THE ANSWER = Z0./ 
23 EVEN 
24 § Build argument block for subroutine on 
25 START: MOV #ANS » ~ (SF ; 
o| MOV #0F 2 9- (SF) ; 
27 MOV #0F 1 9~ (SF) ; 
28 MOV #39-(SP) ; 
© 2 MOV SF yRS ; 
@O- 30 CALL = AAT ; 
34 CALL. PRINT ; 
© 32 CALL SUBB ; 
@ 33 CALL = PRINT ; 
©. 34 CALL MULL ; 
@ 35 CALL PRINT ; 
©. 3% CALL =o DTVy ; 
37 CALL PRINT ; 
38 EXIT$S 3 
39 | 
490 kX FRINT - Frints the results of 
41 PRINT? MOV #OUT »RO ; 
42 MOV FORMAT » RA. ; 
43 MOV #ANS 9 R2 ; 
44 CALL $E0MSG ; 
AS QIOWSS #FIOWWVEy eS eb yore 
46 ; 
47 RETURN ; 
48 sEND START 
Run Session 
*INS LIB 
>RUN USELIRB 
THE ANSWER IS 10. 
THE ANSWER IS 6. 
THE ANSWER IS 16. 
IS 4. 
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DEVICE COMMONS 


A device common is a special type of common that occupies 
physical addresses on the I/O page. Instead of physical memory, 
the I/O page contains peripheral device registers. Therefore, a 
device common does not contain data the way a regular resident 
common does. 


A device common is really just a way of setting up addressing 
to allow a task to manipulate the device registers directly. This 
might be useful in checking out the proper commands needed to 
control a device or to check what control status registers (CSRs) 
are in use on your system (Example 7-4). Obviously, extreme care 
must. be used if you manipulate a device which is also referenced 
by any system routines (e.g., a system device driver). 


Privileged tasks which map to the Executive can also 
automatically map the I/O page. However, privileged tasks must be 
written very carefully to avoid causing additional problems for 
the running system. Device commons allow nonprivileged tasks to 
Manipulate device registers. 


Use the procedure outlined below to create a device common 
and a referencing task. The outline includes the specific steps 
for Example 7-4. It has a device common, DEVICE.MAC, which covers 
the entire I/0 page. The referencing task, CSR.MAC, checks each 
address on the I/O page to find out which CSRs are in use. If a 
nonexistent CSR is found, a nonexistent memory error synchronous 
system trap (SST) results. Use the following steps to create the 
device common. 


1. Create a device common partition which includes’ the 
desired device register addresses. 


e Identify the addresses of the needed device registers, 
uSing the PDP-11 Peripherals Handbook or information 
available from your hardware installation. 


e Determine the base address of the partition at a 
19@(8) boundary below the first identified address. 


- Mapping always begins at a 32-word block boundary. 


Example 7-4 covers all of the I/O page. On a PDP-11/79 or 
other PDP-11 with 22-bit addressing, it starts at physical 
address 17760900(8). On a system with 18-bit addressing, 
it starts at 760000(8). On a system with 16-bit 
addressing, it starts at 160000(8). 
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For a 22-bit system the command is: 


SET PARTITION: DEVICE/ BASE: 1776@0/SIZE: 200@/DEVICE 


For a 16-bit or 18-bit system, use the appropriate base 
address in 32-word blocks. 


Note that you don't need to eliminate an existing 
partition the way you did for resident commons’ and 
resident libraries. This is because there isn't any real 
partition already on the system, because the I/O page does 
not correspond to physical memory. 


you also don't need to create the partition until after 
you create the shared region. However, you do have to 
know its base address before you write the code for the 
device common, so that you can set up the offsets to the 
locations you plan to reference. 

Code the shared region. 


e Do not initialize any ego GT eret Since there is no 
physical memory. 


e Set up for an appropriate referencing technique’ to 
address the desired registers. 


- Use .=.+n or .BLKB.n to get to the first address. 


- Use .BLKB ofr -BLKW statements to reserve the 
needed space (or addresses). 


The following note is keyed to DEVICE.MAC in Example 7-4. 

1) Because you access the entire I/O page, mark the start 
of the region with the global symbol FCSR. The .BLKW 
4896. directive reserves a full 4K words of addresses 
for the entire I/O page. 


Assemble the device common, 


>MACRO/LIST DEVICE 
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Task-build the device common. 


>LINK/OPTION/MAP/N OHEADER/ SHAREABLE: LIBRARY- 
->SYMBOL TABLE DEVICE 

Option?  STACK=@ 

Option? PAR=DEVICE: 160000: 20000 

Option? <RET> 


This command task-builds the region absolute. You can 
also task-build it position independent. 
Install the device common before you run the referencing 


task. Unlike a resident common, a device common is not 
loaded into memory because it has no real contents. 
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Use the following steps to create the referencing task. 


ses 


4. 


Code the referencing task using the corresponding 
referencing technique. See the notes which are keyed to 
the example below. 
Assemble the task. 


>MACRO/LIST CSR 


Task-build the task to reference the device common. 


>LINK/MAP/OPTION CSR 
>Option? RESCOM=CSR/RO 
>Option? <RET> 


After installing the device common, install and/or run the 
referencing task. 


The following notes are keyed to CSR.MAC in Example 7-4. 


Use the global symbol FCSR to reference the start of the 
device common. 


SST vector table with one entry for nonexistent memory. 
NONE is the address of the SST routine. (See Example 2 
for an SST example.) 


Two words for a range of good CSR addresses. The 
addresses are offsets into the I/0 page (@(8) to 
17777(8)). FIRST is set initially with 4@; LAST is 


updated on each read of a CSR. If you ever trap due to 
nonexistent memory, print the range of addresses, set 
FIRST for the first address in the next’ range, and 
continue, 


Set up for SST, uSing just one table entry. 
Count of good addresses in a range. This is used to avoid 


printing a message if a number of consecutive addresses 
are not in use. 
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Set first range to start with offset @ into I/O page. 


Test (or read) the word and increment R4. Control passes 
to the next instruction if the CSR is in use; an SST 
results if it is not in use. 


Increment count of good addresses. 


Check to see if you are at the end of the I/o page. 
Branch back if not. 


When at the end of the I/0 page, display the last range 
and exit. 


SST routine, entered for nonexistent memory trap on the 
TST(R4)+ instruction. Check for some good addresses in 
this range. If none, do not print a message. 


Calculate offset to the last good CSR. The last one 
tested was bad, plus autoincrement incremented R4 by two. 
Therefore, the current contents of R4 are four bytes 
higher than the last good CSR. Also, convert the virtual 
address to an offset from the beginning of the I/0 page. 
Move the last good CSR address to LAST. 


Fdit the range message, and convert the first good and 
last good addresses to unsigned octal. Then display the 
message. 


Set up for the next range and return from the trap. The 
return picks up at line 49 (INC R5). We want R5 to be 
zero after it is incremented, so place a -l in R5. Set up 
the first good CSR address in FIRST as the offset into the 
I/O page corresponding to the current address in R4. R4 
has already been incremented past the CSR which is not in 
use. Return from trap at line 49, and continue check of 
CSRs, unless you have already reached the end of the I/0 
page. 


On the Run Session - This command has probably been issued 
already to create the device partition. It is included 
here for documentation purposes, and in case it has not 
been issued previously. 
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1 *TITLE TEVICE 

2 »IQENT /O017 

3 *ENABL LC § Enable lower case 

4 3 

3 + File DEVICE.MAC 

é 3 

7 > This Program sets ur a device common Por the I/0 rase 
8 3 

9 ¢ Task-build instructions? Must include /SHAREABLE tL IBRARY 
10 § amd /NOHEALER switchess STACK=0+ FAR=NEVICE ortions. 
11 § Must create «STB file. May be /CODESFIC or shsolute 
12 § (the default). 
13 j 

14 § Install and run instructions? DEVICE must be installed 
15 § before running any referencing task. 

16 3 

17 + The code is Felaced in the default blank Psect. Psect 
18 > conflicts are avoided by using the /SHAREABLE SLT RBRARY 
19 ¥ task-builder switch. 
20 ; 

@ 2: FCSRii + BLRW 4096. * Set ur area 4K words lons 

22 *ENT | 

1 «TITLE CSR 

2 +IQENT 7/017 

3 3+ 

4 i File CSR.MAC 

ra 3 

& + This task disrlaus the CSR addresses that ere in use 
7 y om your system. The addresses are listed as offsets 

8 5 into the I/0 rase 

9 3 

10 § Task-build instructions? 

11 ; : 

12 3 LINK/MAF /OF TION CSR 

13 ; Ortion? RESCOM=TEVICE/RO 

14 3 Ortion? <RETS 

15 3 

16 y Install and rum instructions? The device common DEVICE 
17 y must be installed nefore running CSR. 

18 i 

Lo *MCALL QTOWSS+EXITHtS + SVTKSC § System macros 
29 *+NLIST EEX § To nat list binary 

21 3 xtensions 
22 § SST vector table . 


@23 vec: -WORD == NONE 3 Nonexistent memory 


Example 7-4 Creating and Using a Device Common (Sheet 1 of 3) 
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24 
0/2: FIRST? .BLKW 1 y First stood CSR address 
26 LAST? + BLISW 1 § Last CSR address 
27 3 before trarrins 
2B HIF 2 *ASCII /£ XXCSR’S IN USE ON SYSTEM? XX/215> 
29 *ASCII <12>° (CADDRS ARE OFFSETS INTO I/0 FAGE) “ 
30 *ASCITI “15><12><12> + Header text 
Si LHI =, -HIIR § Length of header text 
32 MES? *ASCIZ /CSR’S AP THROUGH ZF ARE IN USE/Z ¢ Text 
33 ¥ for each sood CSR ranse 
34 RUFF? + BLAKE 100. y Outeut messase buffer — 
35 +EVEN 
36 *+ENABL. LSE 
37 
(4 38 START! SVTK#$C VECeo1 § Set ur SST vector to 
39 > handle trar 
40 QIOWSS #LTOWVB vs tS rth es se CHR LHR» #402 
41 > Lliselay header text 
1] 42 MOV #FCSReR4 $ Set base address in 
4S y I/O rage 
| 44 CLR RS § Count of addrs found 
O45 CLR FIRST ; Offset to first CSR 
4S > addriin use 
47 ’ Test addressy causing trar if not in use 
© 48 1$3 TST (R4)+ § Is this a sood addr? 
49 INC RS > Yess increment count 
ro) 50 CMF #<FCSR4+17776>2R4 $ At end of I/0 rase? 
ol BRHIS 1$ § Branch back if mot yet 
wae ys Disrlay last sood ranse and exit 
33 MOV #177762LAST > Fut last CSR in LAST 
34 MOV #RUFF 9 RO $ Set ur for $E0MSG 
© aba MOV #MES sRi1 3 
36 MOV #FIRST»R2 3 
a7 CALL $E0MSG §j Edit range message 
58 QlIOWSS #10. WVBR es tS et) x9 ye RUPP eRe $402 
a? i Diselay range message 
60 EXIT#S 
41 
62 * SST routine for non-existent memory Cor CSR not in use) 
63 
64 NONE? TST RS § Amu sood addresses in 
@| & } this range? 
£66 BEQ OUT + Noney nothing to erint 
&7 MOV R4sR3 + Calculate offset to 
12] 68 ; last sood CSR 
69 SUR F< FCSR+4> e RS ] 
70 MOV R3*LAST Fut last CSR in LAST 
® 71 MOV #BUFF » RO * Set ur for $E0MSG 


Example 7-4 
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2 MOV #MESeR1 y 
73 MOV #FIRSTy»R2 > : 
® | 74 CALL $ELIMSG ; Edit rande messade 
73 QLIOWSS #IOWVR #52 #19 oy o SHBUFF eo RL $402 
7é& ¢ Uisrlay ranse message 
77 § Set addresses and counters for continued search 
78 OUT? MOV #-19RS §¥ Initialize count to -1 
79 § Since RTT returns to 
80 ¥ INC RS instruction 
@ 81 MOV R49R3 ¥ Set ur first good CSR 
82 SUE #F CSR» RS 3 im FIRST 
83 MOV R3sFIRST 3 
84 RTT > Return from trae 
835 +ENT START 


@® >SET FARTITION-: DEVICE/BASE: 1774600/SIZE) 200 /TEVICE 
“INS DEVICE 
*“RUN CSR 
*#¥CER’S IN USE ON SYSTEM? Kk 
CADDRS ARE OFFSETS INTO 1/0 FAGE) 


CSR’S 000020 THROUGH 000106 ARE IN USE 
CSR’S 004200 THROUGH 004234 ARE IN USE 
CSR’°S 005000 THROUGH 005776 ARE IN USE 
CSR‘S 010200 THROUGH 010376 ARE IN USE 
CSR’S 010500 THROUGH 010326 ARKE IN USE 
CSR’S 012200 THROUGH 012376 ARE IN USE 
CSK’°S 012440 THROUGH 0124746 ARE IN USE 
CSR’S 012516 THROUGH 012516 ARE IN USE 
CSR’S 013000 THROUGH 013776 ARE IN USE 
CSR’S 016300 THROUGH 016352 ARE IN USE 
CSK’S 016400 THROUGH 016452 ARE IN USE 
CSR’S 016500 THROUGH 0146506 ARE IN USE 
CSR’S 016700 THROUGH 016752 ARE IN USE 
CSR’S 017170 THROUGH 017176 ARE IN USE 
CSR’S 017340 THROUGH 017356 ARE IN USE 
CSR‘S 017400 THROUGH 017416 ARE IN USE 
CSR’S 017440 THROUGH 017476 ARE IN USE 
CSR’S 017514 THROUGH 017524 ARE IN USE 
CSK’°S 017546 THROUGH 017546 ARE IN USE 
CSR’S 017540 THROUGH 017476 ARE IN USE 
CSR’S 017740 THROUGH 017752 ARE IN USE 
CSR‘°S 017760 THROUGH 017776 ARE IN USE 


Example 7-4 Creating and Using a Device Common (Sheet 3 of 3) 
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Appendix F contains information about several more advanced 
shared region topics. It includes a discussion of: . 


e Overlaid shared regions 


e Referencing several shared regions from one referencing 
task 


e Handling interlibrary calls 
e Cluster libraries 


Most of the techniques discussed are more appropriate for the 
advanced MACRO-11 programmer who is running into virtual address 
limitation problems. Cluster libraries are designed to save 
virtual address space in tasks which uSe DIGITAL layered products, 
such aS FORTRAN, Forms Management Services (FMS), and File Control 
Services (FCS). If you write FORTRAN programs which use these 
products, you may find it useful to read just the last few pages. 
These cover the procedure for task-building a task which 
references two or more DIGITAL Supplied resident libraries as a 
set of cluster libraries. 


Now do the tests/exercises’ for this module in the 
Tests/Exercises book. They are all lab problems. Check your 
answers against the solutions provided, either the on-line files 
(should be under UFD [2@2,2]) or the printed copies in the 
Tests/Exercises book. 


If you think that you have mastered the material, ask _ your 
course administrator to record your progress on your Personal 
Progress Plotter. You will then be ready to begin a new module. 


| If you think that you have not yet mastered the material, 
return to this module for further study. 
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DYNAMIC REGIONS 


INTRODUCTION 


The last module discussed how to use the Task Builder to 
create and access static regions. It is also possible to create 
and access regions while a task is executing. Such regions are 
called dynamic regions. The memory management directives allow a 
task to create and access dynamic regions and to access existing 
Static or dynamic regions. In addition, they offer a facility for 
creating private regions and for allowing other tasks to access 


these regions. 


OBJECTIVES 


1. To write tasks which create a dynamic region and access 
dynamic and/or static regions 


2. To write tasks which dynamically control their mapping 


3. To write tasks which create a private dynamic region = and 
allow one or more other tasks to access the region. 


RESOURCE 


@ RSX-11M/M-PLUS Executive Reference Manual, Chapter 3 plus 
specific directives in Chapter 5 
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SYSTEM FACILITIES 


Sometimes a task's needs for memory and for shared regions 
aren't known until run time, or the needs may change at run time. 
Examples are: . 


1. A task (e.g., an editor) needs a temporary work buffer for 
only part of the time the task is active. 


2. A task needs a shared region or work buffer, but its size 
depends on the needs of the user running the task (e.g., 
the size of an input file). 


3. A task creates a shared region and wants to control access 
to it by other tasks. 


4. A task wants to create a shared region in a_e system 
controlled partition (e.g., GEN) instead of in a dedicated 
common type partition. Then when the shared region isn't 
needed, the space is automatically available for other 
system needs (tasks, etc.). 


5. A task needs to map to two different shared regions at 
different times, but has only one 4K word virtual address 
window available, 

Special directives, called memory management directives, are 
available on mapped systems to allow tasks to perform the 
following functions. 

e Create regions in system controlled partitions 

e Attach/detach from a region 

e cCreate/feliminate virtual address windows 

e Map/unmap a virtual address window to an attached region 

e Obtain information about its mapping from the system. 

The memory management directives are a SYSGEN option. 
Therefore, if users on a system plan to use them, they must be 


included in the Executive at SYSGEN time. Check with your system 
manager to find out if they have been included on your system. 
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REQUIRED DATA STRUCTURES 


Each memor 
of two data 
block (RDB) or 
WDB are the 
Their contents 


y management directive requires that you set up one 
structures within your task - a region definition 
a window definition block (WDB). The RDB and_ the 
interface between the user task and the Executive. 
change dynamically as regions are created and 


accessed. In general, once the WDB and/or the RDB are set up, the 
actual memory management directive macro calls are completely 


straightforward 
XXXXSX wdb 
Or 


XXxXXSx rdb 


where 
wdb - the 
rdb - the 


Examples: 


- Their format is either: 


label or address of the WDB 
label or address of the RDB 


CRAWSC WDB 
CRRGSS  #RDB1 


As with other executive directives, the $, SC, or $S form of each 
directive may be used. 


Region Definition Block (RDB) 


An RDB con 
to attach to 
is used by the 

1. Attach 
26 Create 


3. Detach 


tains information needed to create a region and/or 
a region in a system controlled partition. The RDB 
following directives. 

Region (ATRGS) 

Region (CRRGS) 


Region (DTRGS) 
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ARRAY RDBBK$ SYMBOLIC BYTE 
ELEMENT ARGUMENT OFFSET BLOCK FORMAT OFFSET 
0 
2 
4 
irdb (3) 
nam R.GNAM NAME OF REGION (RADS50) 6 
irdb (4) 
10 
irdb (5) 
par R.GPAR REGION’S MAIN PARTITION NAME (RAD50) 12 
irdb (6) 
14 
— 16 


TK-7733 


Figure 8-1 The Region Definition Block 
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Figure 8-1 shows the layout of the RDB along with the 


symbolic 
an RDB. 


offsets. Use the RDBBKS macro to create and initialize 
Figure 8-1 also shows the RDBBK$ arguments for’ the 


various RDB elements. The meaning of the elements is as follows. 


Region ID —- a unique number assigned to a region when your 
task attaches to a region. The number associates the task 
with the region and is returned by the Executive after 
your task attaches to a region. 


Size of Region - the size of a region to be created, in 
32-word blocks. It is also returned by the Executive when 
attaching to an existing region. 


Name of Region - up to six characters. It is assigned 
when a region is created and used when attaching to a 
region. 


Region's Main Partition Name - the name of the system 
controlled partition. 


Region Status Word - used by the user task to- send 
information to the Executive when creating or attaching to 
a region. Also used by the Executive to return status’ to 
the task after a memory management directive is executed. 
See Table 8-2 for a list of the various bits and _ their 
meanings. 


Region Protection Word - analogous to the file protection 
word, controlling access to regions. As shown below, it 
is set up with the same format (RWED for read, write, 
extend, delete) within each category; or: system, owner, 
group, and world. 


World Group Owner System 

DEWR DEWR DEWR DEWR 

1119 1119 ay) COBO = 167800(8) 

A 'l' means access is denied, a '@' means access is 


permitted. So the example means that world and group have 
just read access, and owner and system have all accesses. 
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Table 8-2 


RS : 
Se ee 


SERS 4 


ee 
oe 


ee 
EO OSES 
ee. : 


ee 
Bea 
See S. 
_ 


oe 
Cee: 


seenemee nani 


SOG ae: 
EOS eee ce, 
-s ES a OR i 
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Creating an RDB in MACRO- 11 
The format for the RDBBKS macro call is: 


RDBBKS siz,nam,par,sts,pro 


No argument is provided for the region ID because it is 
always returned by the Executive and is never specified by the 
user. See Table 8-2 for a list of the region status word bits, 
including their symbols and meanings. We will discuss these 
further when we discuss the individual directives. Any 
information not filled in at assembly time using the RDBBKS macro 
can be filled in using direct MOVs at run time. 


Examples: 


To create an RDB for use in creating a region with: 


Size in 32(1@) word blocks = 2 

Region name = MYREG 

Partition name = GEN 

Region to be attached on create 

Region to be marked for delete on last detach 

Write access desired on attach 

Owner to have all privileges and group to have read 
privileges. 


RDBBKS 2,MYREG, GEN ,<RS.ATT! RS.MDL!RS.WRT>,177017 
Expansion: 


.- WORD Q 

.-WORD 2 

-RAD5@ /MYREG/ 
- RAD5@ /GEN Vd 


Region ID 
Region size 
Region name 
Partition name 


~e "0 MO NO 


-WORD <RS.ATT!RS.MDL!IRS.WRT> ; 900242(8) Region status 
: word 
-WORD 177817 : Region protection word 
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The example below shows the use of a MOV inStruction to. set 
the region size at run time. 


To create an RDB for use in creating a region with: 


Size in 32(18) word blocks = 1@900(8) 

Region name = XXXX 

Partition name = same as task is installed in 

Region status = do not delete, desired access to be filled in 
before attaching 7 

World to have no privileges, all others to have all privileges 


RDBBKS @,XXXX,,RS.~NDL, 179009090 


Expansion: 


-WORD 178 888 


-WORD g ; Region ID 

-WORD g ; Region size 

- RAD5@ JXXXX / ; Region name 

~WORD 0, ; Partition name 

-WORD RS.NDL : 100(8), Region status word 
a 


Region protection word 


MOV #1800,RDB+R.GSIZ ; Set region size at run time 
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Window Definition Block (WDB) 


A WDB contains information needed to create a virtual address 


region 
The WDB 


and to map a virtual address window to an attached region. 
is required for the following directives. 


Create Address Window (CRAWS) 
Eliminate Address Window (ELAWS) 
Map Address Window (MAPS) | 
Unmap Address Window (UMAPS) 
Send by Reference (SREFS) 


Receive by Reference (RREFS). 


Figure 8-2 shows the layout of the WDB along with the 
symbolic offsets. Use the WDBBKS macro to create and initialize a 
WDB. Figure 8-2 also shows the WDBBK$ arguments. The meaning of 
the elements is as follows. 


Window ID - A number which identifies the window block in 
the task header which describes the window. Window @Q is 


‘used for the task window. Windows 1-7 are used _ for 


additional windows set up by the Task Builder, for 
overlays and static regions, and for windows created 
dynamically. The window ID is returned by the Executive 
after a Create Address Window directive. 


Base APR - The base APR to be used in mapping the window, 
which sets the base virtual address. 


Base Virtual Address - The base virtual address in octal; 
returned by the Executive after a Create Address Window 
directive. 


Region ID - The region ID, used to identify the region 
when mapping a virtual address window to a region. It is 
returned by the Executive in the RDB after an Attach 
Region directive. You must move the value returned from 
the RDB to the WDB before mapping to the region. © 


NOTE 
The Task Builder option WNDWS=n must be used 
to specify the additional number of window 
blocks needed for dynamic windows. 
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ARRAY WDBBK$ SYMBOLIC . BYTE 
ELEMENT ARGUMENT OFFSET BLOCK FORMAT OFFSET 
W.NID 0 


iwdb (1) 


BASE APR WINDOW iD 


apr W.NAPR 2 
4 

6 

10 

12 

14 

16 


TK-7736 


Figure 8-2 The Window Definition Block 


Offset in Region (32-word blocks) - The offset within the 
region at which mapping is to begin. It allows a task to 
map to different portions of a region. 

Length to Map (32-word block) - The length within the 
region to be mapped. It defaults to the shorter of the 
Space remaining in the region and the size of the window. 


Window Status Word - Used by the user task to_- send 
information to the Executive when creating and mapping 
windows. It is also used by the Executive to. return 
status to the user’ task after a directive is executed. 
Table 8-3 lists the various bits and their meanings. 


Send/Receive Buffer Address - The address of an 8-word 


buffer for sending or receiving data as part of the Send 
by Reference and Receive by Reference directives. 


348 


DYNAMIC REGIONS 


Creating a WDB in MACRO-11 
The format of the WDBBKS macro is: 


WDBBKS apr,Siz,rid,off,len,sts,srb 


Note that no argument is provided for either the window ID or 
the base virtual address, because these elements are always 
returned by the Executive. Table 8-3 shows a list of the window 
status word bits, including their symbols and meanings. We will 
discuss these further when we discuss the individual directives. 


Table 8-3 Window Status Word 


a oo 
So ee oe 
oe He : 
oie aa oe 


208: 


SG es 
oo 


oe 
a 
Be ss 
oe 


peace 


S 


oA 


ie 
a 
oe 
oe 


f 


Oe: 
= 


See 


Ss 
PRE ees nee ESS 
=. srt—i‘a*eC*zsOwOCWW 
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Examples: 


To create a WDB to describe a window with the following: 


APR = 7 

Size in 32(1@) word blocks 
Region is to be mapped in a 
Map with read access. 


WDBBKS 

Ex pansion: 

~BYTE G,7 ; 
-WORD g ; 
.WORD 100. ; 
- WORD i) ; 
-WORD Q ; 
-WORD 108. : 
. WORD WS.MAP!IWS.RED ; 
-WORD g ; 


To create a WDB to describe 
characteristics: 


APR = 5 

Size in 32(1@) word blocks 
Map starting at offset of 5 
1@(1@) blocks 


108 (10) 
CRAWS or RREFS directive 


7,190.,0,80,190.,<WS.MAP!WS.RED> 


Window ID, APR 

Base virtual address 

Length 

Region ID 

Offset in region 

Length in region 

@20201(8), window status word 
Send/Receive buffer address 


a window with the following 


208 (8) 
blocks in region and map 


Send with delete and write access. 


WDBBKS 


Expansion: 


- BYTE 0,5 ; 
-~-WORD Q ; 
-WORD 200 ; 
~WORD 1 ; 
-WORD 5 ; 
-WORD 10. : 
~WORD WS.64B!WS.WRT! WS. 

tA 
-WORD Q ; 
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DEL ; 


5,200,0,5,10.,<WS.64B!WS.WRT! WS. DEL> 


Window ID, APR 

Base virtual address 
Window length 
Region ID 

offset in region 
Length in region 
@020412(8), Window status 
word 


Send/Receive buffer address 
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CREATING AND ACCESSING A REGION 


Use the following procedure to create and access a region. 
1. Create the region (Create Region directive). 

2. Attach to che region (Attach Region directive). 

3. Move the region ID from the RDB to the WDB. 


4. Create a virtual address window (Create Address Window 
directive). 


5. Map the virtual address window to the region (Map Address 
Window directive). 


6. Use the region. 


7. Detach from the region (Detach Region directive or task 
exit). 


Steps 1 and 2, and also steps 4 and 5 can each be combined in 
a Single directive call. Step 4 can be performed earlier, if 
desired. To access an existing region, begin with step 2. 


If you don't remember what windows and regions are, or _ what 
attaching and mapping mean, look over the sections on Windows and 


Regions in the last few pages of Module 5 on Memory Management. 


The use of each directive in the procedure above is detailed 
on the following pages. The discussion includes the purpose of 
the directive, important input and output parameters, and notes 
about its use. For a complete discussion of each directive, see 
Chapter 5 of the RSX-11M/M-PLUS Executive Reference Manual. For 
additional information on the memory management directives, see 
Chapter 3 of the same manual. 
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Creating a Region 


When you create a region, the Executive allocates space for 
it in a system controlled partition. Use the Create Region 
directive (CRRGS) with the following RDB input parameters. 


e Size of region (in 32(18) word blocks) 
e Name of region (becomes a private region if no name) 
@ Name of partition (defaults to partition of task) 


e Region status word - mark for delete or do not delete 
(default is mark for delete) 


e Region protection word - determines permissible access to 
region. 


The only RDB output parameter is the RS.CRR bit in the region 
Status word. It is set if the region is successfully created, and 
cleared if not. Normal Executive directive status is returned as 
well (carry set for error, clear for success; DSW contains 
directive status word). If the region already existsS, success 
status is returned. Therefore, RS.CRR can be usSed to tell whether 
the region was in fact created, or whether it already existed. 


Any task which passes the protection test can attach to a 
named region. For unnamed (private) regions, only tasks which are 
specifically attached by the creator of the region may attach _ to 
aig a Therefore, for a private region, the creator completely 
controls which tasks attach to it and their access rights as well. 


By default, or if RS.MDL is set in the region status’ word, 
the region is deleted when the last attached task detaches from 
the region. Named regions are left in existence after the last 
detach if RS.NDL is set in the region status word when the region 
is created. Unnamed (private) regions are always marked for 


delete (deleted on last detach). There is no explicit Delete 
Region directive. 


If the RS.ATT bit is set in the region status word, the 
Executive also attempts to attach the task to the region. In this 
case, additional RDB input parameters are required, and additional 
output parameters are returned. Attaching to a region is 
discussed after Example 8-1. 
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Example 8-1 shows how to create a named region which is left 


in existence on last detach. The following notes are keyed to the 
example. 


ed Set up the RDB. RS.NDL set specifies that the region is 
to be left in existence. 


World Group Owner System 
DEWR DEWR DEWR DEWR 


Region protection word = 1111 GBB OOO GOOG (2) 
i yh 4) ) ) (8) 


- Bit set means access is to be denied. 


@ Issue the directive to create the region, specifying the 
RDB address as the only argument. Here we use the $C form 
of the directive. Any form is allowed. 


@ check for a directive error. 


@ Display message and exit. 
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1 *TITLE CRERG 
2 eIQENT /017 
3 *ENABL LC y Enable lower case 
4 3+ 
3 > File CRERG.MAC 
& ; 
ie * CRERG creates & named resiionys and exitsy 
8 § leavins the resion in existence. 
9 7 
10 *MCALL EXITSSsROUBBKSeCRRGSC § System macros 
Li *MCALL QTOWSC »QTOWSS 
12 RIVE 3 REBBKS$ LOOsMYREGsGENyRS.NDIL » 170000 
13 3 lefine restian with? 
14 5 Size = 100 (32. word blocks) 
15 3 Name = MYREG 
16 ; Fartition = GEN 
17 ; Frotection = WO?NonersSY?2RWED 
18 3 OWS RWEDy GRIRWED 
19 5 To not mark for delete on last detach 
20 SMES? *ASCIT /CRERG SUCCESSFULLY CREATED MYREG/ 
2 LSMES =,~SMES 


22 BUFF ¢ + BLE 
2d EFMT$ sASCIZ 
24 +EVEN 


3 
26 START? CRRG¢C 


(3 yz RCS 


28 QTOWSC 
29 

30 EXIT#S 
31 > Error code 
32 ERR? MOV 

33 MOV 

34 MOV 

35 CALL. 
36 QLOWSS 
37 

38 EXIT#S 
39 »ENT 


Run Session 


SRUN CRERG 


Example 8-1 


80. ’ €ENMSG buffer 
/ERROR IN CREATING REGION. SW = 
ROE i Create resian 
ERR , § Branch on dir 


IO.WVUBsSoleeve ei SMES»LSMESs 40> ¢ 


Alle / 


error 
Write 
§ S§UCCess messase 


§ Exit 
#FEFMT sR § Set ure for $ETNSG 
EENSWR2 rf 
#ERUFF » RO 3 
$E0MSG i Egit error message 
ETO.WVUB yo #59 hi yoy oe SKRUPF eo Rie #402 ¢ Write 
+ messade 
> Exit 


START 


Creating a Named Region 
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Attaching to a Region 


When you attach your task to a region, the Executive creates 
a logical connection between the two. The region can be either a 
dynamic region or a static region. Use the Attach Region 
directive (ATRGS) with the following RDB input parameters: 


@e Region name | 
e Region status word (indicating R,W,E,D access) 


The following RDB output parameters are returned: 


e Region ID 
e Region size 


The region ID is needed later in order to map ae virtual 
address window to the region. The region size is of interest when 
attaching to an already existing region whose size may not _ be 
known. 


Attaching can also be done as part of the Create Region 
directive (CRRGS), if the RS.ATT bit in the region status word is 
set when the Create Region directive is issued. In fact, for an 
unnamed region, attaching must be done as part of the Create 
Region directive, since there is no region name to be used in a 
separate Attach Region directive. 


A task can detach from a region by using an explicit Detach 
Region directive (DTRGS$) or by exiting (the Executive detaches the 
task). If a task is changing a region from do not delete to mark 
for delete, an explicit detach is required with RS.MDL set in the 
region status word. If the task exits without issuing an explicit 
detach, the Executive detaches the task but does not mark the 
region for delete. Once a region is marked for delete, it is 
deleted when the last attached task detaches from it. Once it is 
marked for delete, it cannot be changed to "do not delete." If a 
fixed task exits without issuing an explicit detach, no detach is 
performed by the Executive. 


355 


DYNAMIC REGIONS 


Creating a Virtual Address Window 


When you create a virtual address window for a task, _ the 
Executive initializes a window block in the task header. It also 
checks to ensure that this is the only window that uses’ the 
specified range of virtual addresses, unmapping and eliminating 
any window that overlaps that range. Use the Create Address 
Window directive (CRAWS) with the following WDB input parameters. 


e Base APR number 
e Window size (in 32(1@) word blocks) 


The following WDB output parameters are returned: 


e Window ID assigned by the system (1-7) 
e Base virtual address 


The space for the additional window blocks in the task header 
must be reserved at task-build time using the WNDWS=n option. N 
is the number of additional windows needed for windows created at 
run time. If extra space is not allocated, an address window 
allocation overflow error (IE.WOV = -85.) results. 


The window is also mapped to a region if bit WS.MAP is set in 
the window status word when the Create Address Window directive is 
issued. In that case, addition input parameters are needed. See 
Mapping to a Region in the following section. 


The Eliminate Address Window (ELAWS) directive can be used to 
explicitly eliminate a virtual address window. In general, it is 
not used, because creating a new window automatically eliminates 
any overlapping window. 


Mapping to a Region 


When you map a.virtual address window to a region, the 
Executive creates a logical connection between the virtual address 
window and the region. Any attached region can be mapped. In the 
process, the memory management registers are loaded. so that 
references to virtual addresses in the window access the region. 
This is assuming, of course, that the task keeps control of the 
CPU. The APRs are reloaded every time a new task takes control of 
the CPU. 
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Use the Map Address Window directive (MAPS) to map a window 
to a region, with the following WDB input parameters. 


e Region ID - Returned to RDB by Attach (move from RDB_ to 
WDB) . 


e Offset into Region - in 32-word blocks, used to. start 
mapping at an offset from the start of the region. This 
must be a multiple of 8(10), unless WS.64B is set in _ the 
window status word, If wWS.64B is set, any whole number 
may be specified. 


e Length to Map - If specified, must be less than, or equal 
to, either the length of the window or the . length 
remaining in the region, whichever is’ shorter. LE 
defaulted, it is set to the shorter of the two. 


e Window status word - actual access desired (read-only, or 
read/write). Read-only is always requested by default. 


The only WDB output parameter generally used is the length 
actually mapped. If the window is already mapped, it is first 
unmapped by the Executive. You can also use the Unmap' Address 
Window directive to explicitly unmap a window. Mapping can also 
be done as part of the Create Address Window directive (CRAWS). 


The type of access desired is used here in addition to when 
you attach to the region, because several different windows in the 
task may map the same region. Some of the windowS may need 
read-only access, others may need read/write access. [In that 
case, you must attach with read/write access, and then you may map 
each window with either read-only or read/write access. 
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Example 8-2 shows how to create a region and place data into 
it, leaving it in existence upon exit. Example 8-3 shows how to 
attach to that region, read and display the data, and then detach 
and mark it for delete. One run sesSSion covers both examples. 
The following notes are keyed to Example 8-2. 


Task-build with the WNDWS=1 option, allocates space in the 
task header for one additional window block. 


We use the $ form of the memory management directives. 


RDB for region. RS.ATT set means Create Region directive 
will both create the region and attach to it. 


WDB for virtual address window. The third argument is for 
the region ID, which will be filled in at run time, after 
the task attaches to the region. In the window status 
word, WS. MAP means that the Create Address Window 
directive will both create the window and map it to the 
region. WS.RED is automatic, even though not specified. 


Create region and attach. Use DIR$ since you are using 
the $ form of the directive. 


Move region ID, returned in RDB after attach, into WDB for 
mapping. 


Create a virtual address window and map it to the region. 


The virtual address window begins with APR 7; therefore, 


the base address in the window is 16@900(8), corresponding 
to the base address in the region. 


Place a byte count, 490(10), in the first word in the 
region. This is just one way to communicate this 
information to other tasks which access the region. The 
length of the region is returned when a task attaches to 
the region. You could use this as an alternate way to 
pass information about the amount of data. 


Move 100(10) words of ASCII "AB" and 1@@(18) words of 
ASCII "12" into the region. This gives you 200(18) words 
or 490(18) bytes of data. 


Display a successful creation and initialization message 
at the terminal. 


Detach from the region and then exit, leaving the region 
in existence. 
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*TITLE CREURG 
+ITENT /0O1/ 
*+ENABRL LC §’ Enable lower case 


File CREURG. MAC 


Frogram to create a named resion Cattached on creation) » 
create a virtual address window (marred on creation) » 


ASCII data in to the regions detach from the 
and exits leaving the resion in existence, 


Taesk~-build instructions? 


SLINK/OFTION/MAF CREURG 
Ortion? WNOIWS=1 
OPTION? <RET> 


*MCALL EXIT&#S» ROBBERS » WORBKS » CRRGS »y CRAWS 
*MCALL UDNTRGS$e DIRS» QTOWSS » QTOWSC 


CRRGS RYE s0FB for create resion 

Tlefine resion with? 

Size = 100 (32. word blocks) 
Name = MYREG 
Fartition = GEN 


WO?None rs SYIRWED» 
OWS RWENy GRIRWED 
To mot mark for delete on last detach 
Attach with ready write and delete access 
= <CRS.NOLIRS.TELIRS.REDIRS.WRTIRS.ATT> 
ROBEKS 100sMYREGsGENsWSWs 170000 


Frotection 


CRAWS WE > DFR for create address window 
Nefine window with? 

AFR 7 

Size 100 (32. word blocks) 


Offset in resion 0 (32. word blocks) 

Length im resion 100 (32. word blocks) 

Mar on create with read/write access 
WHBEKS 7xl002020%1009<WS. MAP IWS.WRT= 


HOH OH OH 


’ DFR for detaching 

§ from resion 

»BLAKW 2 + I/O status block 
*ASCII /CREURG HAS CREATED AND INITIALIZED THE/ 
*ASCII / REGION/ 

=,~TINMES 

format strings 

*ASCIZ /ERROR CREATING REGION. [SW = ZT./ 
*ASCIZ /ERROR CREATING WINDOW. DSW = “~£D./ 
*ASCIZ /UHIRECTIVE ERROR ON QIO. DSW = “£D./ 
*ASCIZ '!1/0 ERROR ON QIO. CODE = Zf.! 

*-ASCIZ ERROR DETACHING FROM REGION. [U1SW = Zl. / 


DTRGS$ ROB 


+ BLAKE 80. § Outeut buffer 


Example 8-2 Creating a Region and Placing 


Data in It (Sheet 1 of 2) 
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36 +EVEN 
6 a START? DIRS #REG > Create resion and attach 
38 RCS ERR § Check for error 
6 39 MDYV ROBR+R.GI0yWHBtW.NRID § Move resion If 
60 § into WIE 
@ 41 DIRS = #WIN $ Create window and mar 
62 BCS ERR2 + Check for error 
rs 63 MOV #160000°R5 § Set base addr im resion 
O«4 MOV #400. (RS) + + Move bute count to ist 
65 § word in resion 
464 MOV #100.%KO § # of words of ‘AR’ data 
67 LOOF? MOV #"ABs CRSD+ § Move chars to region | 
48 SOR RO» LOOF § Tecrement counter and 
© 69 > loor until done 
70 MOV #100.%R0 > # of words of ‘12’ date 
71 LOOPB? MOV #"129C(RS5)+ 5 Move chars to resion 
72 SOK RO»LOOFR y Loor until done 
@ 73 QTIOWS$C IO.WVBsSelssTOSRy »y <0NMESsLONMES » 40> 
74 BCS ERRSIt § Branch on dir error 
73 TSTE IOSE + Check for I/0 error 
76 BLT ERRSTI § Branch om I/O error 
12] 77 NIRS #0ET + Letach from resion 
78 RCS ERR4 ¢ Check for error 
79 EXIT#S 
80 * Error code 
81. ERR? MOV #FCRRERsR1 ’ Create region error 
82 y mMmessedte 
33 RR SHOERR § Branch to common code 
84 ERR2 ? MOV #FCRWER»R1 + Create window message 
85 BER SHOERR > Branch to common code 
86 ERRSIS MOV #FQIONEsR1 § QIO directive messade 
87 BR SHOERR §’ Branch to common code 
88 ERR3I3 MOV IOSB»RO y Extend sigm on status 
B89 MOV RO» $0SW y and move to arg block 
9Q MOV #FQIOIEsR1i § QIO I/0 error 
91 BR SHOERR > Branch to common code 
92 ERR4? MOV #FDETERyR1 + Tetach region message 
93 SHOERR? MOV #EUFF » RO § Set ur for $E0MSG 
94 MOV #$0SWseR2 j 
93 CALL $EDMSG sy Edit message 
96 QIOWSS #IO.WVBy #5 #1999 eC BUFF 9 RL $402 
97 ’ Tlisrlay messade 
98 EXIT$S s Exit 
99> +ENT START 
Run Session 
*RUN CREURG 
CREURG HAS CREATED AND. INITIALIZEN THE REGION 


“RUN ATTURG . 
ABARABABABABABABABABABARABABA BARBARA BABABABABABABABABARARABABARAB 
ABABABABABABABABABABABABABABA BABA BABABABABABABRABABARARBABABABRABAB 
ABABARABABABABABABABABABABABA BABABABABABABABABARBABRABABARARABABAB 
ABABABABI21 21212121 2121 21 2121 2U ZU ZL ZAPU ZAP 2121212121 21212121212 
L2AZUZAZAL ZA ZAPAZA2AZADAL 2A PA QL 21 PAPA PL QA 2A PABA AZAZAZi2L2i 2121212 
L2LZLZAQAZALZLQAZABAZASAL QL SL 2A ZL 2A 212121 2A PAPAZAZUSAZAZ121 2121212 
L2L2L2ZAZ12121212 


Example 8-2 Creating a Region and Placing 
Data in It (Sheet 2 of 2) 
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Example 8-3 attaches to the region created by Example 8-2, 
reads and displays the data, and then detaches from the region and 
marks it for delete. The following notes are keyed to Example 


8-3 e 


Again, task-build with the WNDWS=1 option so that the Task 
Builder allocates space for the window block in the task 
header. 


This example uses all three forms of the directives, for 
illustration purposes. 


The RDB for attaching to the region. In fact, the only 
required information is tthe region name and the region 
Status word. The partition name and size, although 
included here, are not needed. RS.MDL set marks the 
region for delete when we do an explicit detach. You need 
delete access to mark the region for delete (RS.DEL). 
Also, attach with read (RS.RED) and write (RS.WRT) access 
so that you can map with read/write access. 


The WDB for the virtual address window. We map the entire 
region (length = 1@@0(8) 32-word blocks), starting from the 
beginning (offset = @). WS.MAP means create the address 


“window and map. Map with read (WS.RED) and write (WS.WRT) 


access. 


Attach to the region. 


Move the region ID to the WDB; create the virtual address 
window and map it to the region. 


Set base address in region - again 1600#00(8), because the 
base APR is APR 7. 


The first word in the region contains a character or byte 
count. 


Number of characters to print on each line, except’ the 
last line (if it has less than 64(1@) characters). 
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Loop through region, printing 64(1@) characters per line. 
This technique is used to demonstrate how to control the 
width of the output and make the run sesSion fit on an 
8-1/2" by 11" page with margins. If the full terminal 
buffer width (typically 80(190) or 132(18)) is acceptable, 


one QIO directive, with the total character count 
specified for number of characters, would be enough to 
write the entire region, In that case, the terminal 


driver will automatically wrap to the next line after a 
full line is displayed. 


Detach from the region. An explicit detach is required to 
mark the region for delete. 


NOTE 

In Chapter 7, we discussed the fact that a 
task needs read/write access to a region to 
issue QIOs to write directly from a _ region. 
This also applies to dynamic regions. ATTURG 
issues QIOs directly from MYREG. Therefore, 
although it appears that ATTURG only needs 
read access, it actually needs’ read/write 
access. See the discussion following Example 
7-1 in Chapter 7 for additonal information. 
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+TITLE ATTURG 
+IQENT 7/017 
*ENABL LC i Enable lower case 


File ATTURG.MAC 


Frogram to attach to an existing resions create a 
virtual address window (marred an creation)s reac 
ASCII data from the resions detach from the resion 
and exit. The resion will be deleted om last detach. 
The first word in the region contains &@ count of how 
many butes of data are in the region 


Assemble and task-huild instructions? 


“MACRO/LIST LEI CiyLIFROGMACS/LIBRARY »devilufdIATTURG 
SLINK/MAF/OF TION ATTURG»LBEi Cis lL IPROGSUBS/LIBRARY 
-Ortion? WNOWS=1 

>Oretion? <RETS 


*+MCALL EXIT#SsROBRBKS>WORRKSsATRGSC § Sustem 
»MCALL CRAWS es DTRGSS DIRS sQTOWSS y Macros 
*+MCALL DITRERRs TOERR > Surelied macros 


RB? ROBBKS LOOsMYREGyGENs “RS. MIILIRSG  WELIRS.REDIRS.WRT> 
Lefine resion with? 
Size = 100 (32. word blocks) 
Name = MYREG . 
Fartition z= GEN 


Mark for delete on last detach 
Attach with read» write and delete access 


N3 CRAWS WE s0FPR for create address windaw 
Ri WOBBKS 7el0090902100%s<WS. MAF IWS.REDIWS.WRT> 
tefine window with? 
AFR 7 
Size 100 (32. word blocks) 


Offset in resion 0 (323. word blocks) 
Length in resion 100 (32. word blocks) 
Mer on create with read and write seccess 


do OH 


SE? + BLKW 2 + [/0 status block 
ART? ATRGS#C ROB § Attach to resion 
RCS ERR1 > Check for error 
MOV ROB+R.GINyWOR+W.NRID § Move resion IT 
% into WDB 
IRS WIN § Create window 


Example 8-3 Attaching to an Existing Region 


and Reading Data From It (Sheet 1 of 2) 
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BCS 
MOV 
MOV 
MOV 
LOOF QIOWss 


RCS 
TSTE 
BL.T 
SUB 
BLE 
ALT 
CMF 


BLE 
MOV 


BR 
DONE 3 NTRG$S 

BCS 

EXITS 
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ERR2 


#160000 9RS 


(RSd+ 
#GO4A, » 


yk4 
RS 


“> “> “> Wh 


Check for error 

Set nase addr in resion 
Get cheracter count 
Chars rer line 


#IO WVBR #59 #1 o oR TOSBe op TRG9RSs F40> 


ERR3It 
IOSE 

ERR3I 
R39R4 
TONE 

R3*RS 
R39R4 


LOOF 
R49R3 


LOOF 
#ROE 
ERR4 


s Error handlinad code 


ERR1L 3 DIRERR 
ERR2 $ DIRERR 
ERR30s OIRERR 
ERR3I3 IOERR 
ERR4 3 DIRERR 
*END 


“ERRO 
ZERRO 


START 


FR ATTACHING 


“S> “G> “GP > S> “> “Sr “> “Kd “SP “SP “Gr “GSH Gd Co 


Write date 

Check for dir error 

Check for I/0 error 

Branch om error 

Comeute chars left 

Kranch if done 

Foint to next char 
Check for <= 64. chars 
left to erint 

> Or *y Print next line 

“y Print only that many 
chars 

Print the line 

Tetach from resion 
Check for error 


TO REGION? 


R CREATING WINDOW ANT MAFF ING? 
“ERROR WRITING DATA> 

#ITOSBy<ERROR WRITING DATA> 

<ERROR DETACHING FROM REGION? 


Example 8-3 Attaching to an Existing Region 
and Reading Data From It (Sheet 2 of 2) 
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SEND- AND RECEIVE-BY-REFERENCE 


If you create a private (unnamed) region, you have complete 
control over whether other taskS can have access to it. You 
specifically attach other tasks to the region by sending a_ packet 
containing a reference to the region. When you do that, you can 
also specify what access they have to the region. At the time, 
you must be attached with at least that much access yourself. 
Named regions, on the other hand, can be attached by any task that 
knows the name and has the access privileges needed to pass the 
protection check. 


Use the Send-by-Reference directive (SREFS) to send a region 
by reference, with the following input parameters. 


Receiver task name 
WDB ~—- Region ID 


offset into region - sent unchecked to receiver 
length to map - sent unchecked to receiver 

window status word - determines how receiving task is 
attached 


address of buffer - 8(18) word buffer which is sent to 
the receiver 
Event flag - if specified, set when the reference is 
received, not when it is queued up (in the receive- 
by-reference queue). 


The receiver task is attached to the region when the 
reference is queued up. This avoids the problem of the region © 
being deleted if the sender exits before the receiver receives the 
region, Remember that private regions are always marked for 
delete on last detach. 


If you are uSing the event flag for synchronization, note 
that the flag should be used to notify the sender as to when the 
receiver receives the region by reference. It is not the same as 
Send and Receive Data directives, where the flag is set when the 
reference is queued. That flag should be used to notify the 
receiver. 
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The receiver follows a somewhat modified procedure to access 
the region, as follows. 


1. Create window. 


2. After reference is queued, receive by reference (fills in 
region ID in WDB). 


3. Map to region. 
4. Use region, 
5. Detach from region. 


Use the Receive-by-Reference directive (RREF$) to receive a 
reference to a region, with the following WDB input parameters, 


Window Status Word - WS.MAP for receive and map; WS.RCX for 
receive data or exit. 


Buffer Address - 10(19) word buffer for sender task name (in 
Radix-5@ format) and data. 


The following WDB output parameters are returned, all as set 
by the sender: 


Region ID 

offset into region 

Length to map . 

Window status word - describes how attached 


If the WS.MAP bit is set, the Executive maps the window to 
the region, uSing the offset, length, and window status word 
access as sent. If a separate Map directive is used, the receiver 
can first check and/or modify those parameters before mapping to 
the region. WS.RCX set tells the Executive to exit the task if 
there are no packets in the receive-—by-reference queue. 


Although there are ‘some similarities, Send Data and _ Receive 
Data are completely independent from Send-by-Reference and 
Receive-by-Reference. The receive (data) queue is separate from 
the receive-by-reference queue. 


If you want to use ASTs for synchronization, use the’ Specify 
Receive-by-Reference AST directive (SRRAS). This causes’ the 
Executive to transfer control to the specified AST routine when a 
packet is placed in the receive-by-reference queue. Generally, 
issue this directive when the task starts up. 
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Examples 8-4 and 8-5 show how to create a pair of tasks, a 
sender task and a receiver task. The sender, Example 8-4, creates 
a private region, initializes it, and sends a reference to it to 


the receiver. The receiver, Example 8-5, in turn receives the 
reference, displays the data, and then exits. One run session is 
included for both examples. The following notes are keyed to 


Example 8-4. 


@ This program uses the supplied macro DIRERR to generate 
directive error messages. Therefore, PROGMACS.MLB must be 
specified when assembling, and PROGS UBS. OLB when 
task-building. 


@ The RDB for the region. The name is defaulted to create a 
private region. ‘ 


@ The woB for the virtual address window. The length 
actually mapped will be returned after mapping. Read 
access is automatic for map, so WS.WRT gets’7 read/write 
access. | 


4 Create and attach to region, create virtual address window 
and map it to the region. 


@ use the base virtual address in the window (returned in 
the WDB) to set the base address of the region. Since APR 
7 is the base APR, this address is 160000(8). 


Fill the region with ASCII Ms. 


Send-by-reference to RCVREF (Example 8-4). Event flag 1 
will be set when RCVREF actually does a 
receive-by-reference. 


rs ) Display message that a region was created and sent. Then 
wait for event flag 1 to be set. 


Display message saying RCVREF received region, and _ then 
exit. 


@ exit. The Executive will detach you from the region. 
Note that even if SNDREF exits before REVREF receives the 
region by reference, the region will not be deleted 
because RCVREF is attached when the reference is queued. 
The region is deleted only after both SNDREF and RCVREF 
detach. 
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+TITLE SNIIREF 
*IQENT /017 
*+ENABL LC s Enable lower case 


+ 


File SNIIREF.MAC 


SNOREF creates a 64-word (2 block) unnamed region and 
fills it with ASCII cheracters. It then sends the 
region to RCVREFs and them waits for RCVREF to receive 
the resion. (This is signalled by event flags #1.) It 
then Frints 3 messade and exits. Since the area is 


Rum 


“S> “E> “GCP Sh “GP SC? > “GP Se S> “Bh SP “GP Se So > SP “CP “EP “ED 


i 


unmameds it is automatically deleted when the last 
‘attached task exits. 


Assemble and task-build instructions? 


SMACRO/LIST LBiCislIPROGMACS/LIBERARY edevi lufdIsnourer 
SLINK/MAFP/OP TION SNOREP ey LBS Cl» LIPROGSUBS/L I BRARY 
Oetion? WNIWS=1 


Install and rum instructions: RCVREF must he installed. 
SNUREF firsts then rum RCOVREF. 


*MCALL QIOWS$C+QTOWSS»RQASTSC ¢ System macros 
*+MCALL WTSESC+EXIT#Ss RUBRKS » WOREKS 

+MCALL CRRG#S*CRAWSSs SREF SC 

»MCALL DIRERR § Surelied macro 
*«NLIST BEX ¢ SUPPRESS DATA 


* Tefine region with’ 

5 Size = 2 32-WORD BLOCKS 

¥ Name = mone 

r] Fartition = GEN 

3 Frotection = WOtnmonersGRIRWED 

r) OWS RWEDsSYinone 

; Attach on create 

3 Read and write eccess desired on attach 

RF RO =m {70017 

RSTAT = RS.ATTIRS.RED'IRS .WRT 

RORY ROBBK$ 2» yGENesRSTAT es REPRO 

> Tefine window with? 

; AFR u 7 

> Size =z 2 S2-word blocks 

; Offset in resion = O S32-word blocks 

r) Length to mar = QO 32-word blocks (defaults 
3 to smaller of resion 
5 size and window lensth) 
3 Mar om create with read and write access 
WSTAT = WS.MAFIWS.WRT 
WOE? WOBEKS 7x2sO020%¥WSTAT 


Example 8-4 Send-by-Reference (Sheet 1] of 2) 
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04 § 


, 

bale MES13 *ASCII / SNOREF HAS CREATED THE REGION ANT HAS/ 

36 sASCII / SENT IT TO RCVREF./ 

57 LMESI =,~MES1 

58 MES23 “ASCII / RCVREF HAS RECEIVED IT. SNUREF IS NOW/ 

39 *ASCIIT / EXITING.7Z 

60 LMES2 = . ~ MES2 

él +LISt REX § Show binary extensions 

62 +EVEN 

63 *+ENABL LSE § Enable local symbol 

64 . § blocks 

65 START: CRRG$S #kRIIK § Create and attach to 

66 $ Tfesion 
4 | 67 BCS 1% y Branch om dir error 

68 MOV ROB+R.GIDesWOR+W.NRID ¢ Cory resion ID 

&9 y into WEE 

70 CRAWSS #WIiB § Create and mar window 

71 RCS 2% y Branch on dir error 
6 72 MOV WOR+W.NRAS RO + base V.A. of resion 

73 + Fill resion with all M’s 
6 | 74 MOY #64.9R3 y count of words to move 

73 2083 MOV #"MM» CRO) + + Move in am ASCII M 

76 SOB R3» 20% ¥ Loor throush resion 

77 § Send the resionm to RCVREF. EF 1 will be set when 

78 ’ RCVREF recieves it 
@ 79 SREF¢C RCVREF sWORs1 + Send by reference to 

80 * RCOVREF 

821 RCS 3% i Rranch on dir error 

B82 QIOWS$C TO.WVReSy2eeeetMESLyLMESIT»40> ¢ DTiselay 
o| &: y mMessase 

84 RCS 4 > Branch on dir error 

85 WTSE$C 1 y Wait for RCVREF to get 

86 ¥ the resion 

87 RCS os ¢ Branch on dir error 

88 QIOWS$C IO.WVRs Sef eee iMES2»LMES2*40> §¢ DTlisrlay 
9) 89 3 messade 

90 RCS &$ ? Rranch on dir error 
© »: EXIT$S ; Exit 

92 ¢* Error code 

93 1$3 IIRERR <ERROR ON CREATE OR ATTACH REGION> 

94 263 QIRERR <ERROR ON CREATE OR MAF WINDOW> 

95 33 TQIRERR <ERROR ON SEND BY REFERENCE? 

96 4$? QIRERR <ERROR ON 1ST WRITE> 

97 S$ QIRERR <ERROR ON WAIT FOR? 

98 &$3 QIRERR <ERROR ON 2NIt WRITE> 

99 + ENT! START 


Run Session 


SINS RCVREF 

SSET TERMINAL /WIDTH: 64. 

RUN SNOREF 
SNUIREF HAS CREATE 

RUN RCVREF 


THE REGION ANTI 


RCVREF HAS RECEIVED IT. 


HAS SENT IT TO RCVREF. 


SNUREF IS NOW EXITING. 


MMMMMMMMMMMMMMMMMMM MMMM MMMM MMMM MMM MMMM MMMM MMM MMMM MMMM 
MMMMMMMMMMMMMMMMMMM MMMMMMMMM MMMM MM MMMM MMMM MMMM MMMM 


“SET TERMINAL/WIDTH: 80. 


Example 8-4 
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The receiver, Example 8-5, receives a reference, displays the 
data, then exits. The following notes are keyed to the example. 


0 This program uses the supplied macroS DIRERR and IOERR_ to 
- display directive and I/O error messages. 


2 WDB for virtual address window. The size is 29@(8) 
32-word blocks, a full 4K words. The offset into the 
region, the length to map, and the access will be filled 
in on receive. Since the length to map sent by SNDREF is 
two blocks, '2' will be used in mapping. Note that’ the 
window can be more than two blocks long. WS.MAP must be 
left clear until after the window is created. Otherwise, 
the Executive will try to map the window to the region, 
cauSing an error. See the discussion which follows. 


Create the virtual address window. 


Set WS.MAP so that the task will map as part of the 
receive-by-reference. 


Receive-by-reference and map. 


Set base address in region, using base virtual address for 
APR 7 (1680988(8)). 


Get length actually mapped (two blocks, the same as length 
of region) and convert from blocks to bytes. Just display 
that many characters. 


Display all characters with one QIO directive. Note on 
the run session that we set the terminal buffer to 64(19) 
to allow for margins on an 8-1/2" by 11" page. 


@ exit. The Executive will detach the task from the region. 
When both tasks have detached, the region will be deleted. 


The receiver may map after the receive-by-reference or as 
part of the receive-by-reference. If the receive-by-reference and 
the map are combined in one directive, issue the 
Receive-by-Reference directive with the WS.MAP bit set. [In that 
case, the WS.MAP bit must be clear when the window is created, 
Since you can't map until you receive. This is necessary because 
even though the receiver is attached to the region when the 
reference is queued up, the region ID isn't filled in the WDB 
until the receiver executes the Receive-by-Reference directive. 
Therefore, if you receive and map in one call, issue the Create 
Address Window directive with the WS.MAP bit clear; then set it 
before issuing the Receive-by-Reference directive. If you use a 
separate Map directive, the WS.MAP bit can be left clear. 
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1 »TITLE RCVREF 

2 *IQENT /017 

3 *«ENABL LC * Enable lower case 

4 3+ 

§ § File RCVREF.MAC 

& 3 

Z * Frosgram to receive-by-reference a resdion from SNEIREF y 
8 3; har to the resions read ASCII data from the resiony,: 

9 y detach from the region and exit. The resion will be 

10 § deleted om last detach. 

11 r 

12 ¥ Assemble and tagsk-huild instructions? 

13 3 
14 3 MACRO/LIST LE& Cis lL IFROGMACS/LIBRARY s devi CufdIRCVREF 
13 3 LINK/MAF/OF TIONS RCVREF sL Bi Cis LIPROGSUBS/LIBRARY 
16 ry Oretion? WNDWS=1 

17 ; Oetian? <RETS 

18 3 

i? § Instell and run instructions? RCVREF must be installed 
20 * Rum SNOREF first and then rum RCVREF 
z! $ 
22 *MCALL EXIT#SsWOBRERS»RREF¢ §&¢ External sustem 
2g *MCALL QIOWSS +s CRAWS s DIRS 5 Macros 
24 »*MCALL DITRERR» TOERR ¢s External gurrelied 
25 3 macros 
26 ? Yefine window with? 

27 } AFR a 7 

28 3 Size = 200 (32. word blocks) 
2° 3 Allow for full AFR 
30 3 These are filled in on receiver as set bu sender? 
31 ? Offset in resion = 0 (32. word blocks) 
32 3 Lensth im restiom = 0 (32. word blocks) 
33 ; reset when marred 
34 5 ACCeaSS = OQ 
35 § Note? Must mar after receivins Cor as rart of receive) 
34 WOE? WORRBKS 7200 

37 3 
38 REC3 RREF WINE : Set ur TFB for RREFS 
3F WIN? CRAWS WB §. Set ur DFE for CRAWS 
40 IOSE? +BLKW 2 § I/O status block 
4i 
42 START? DIRS #WIN * Create virtual address 
43 § Window 

44 RCS EPR 1 + Branch om error 

43 RIS #WS.MAP yWOR+W.NSTS ¢ Set WIR to mar on 
46 ¥ receive 


Example 8-5 Receive-by-Reference (Sheet 1 of 2) 
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@ 4+ DIRS 
48 
49 RCS 
50 MOV 
Si 
aE MOV 
53 MUL 
© 4 QIOWSS 
555 
54 RCS 
57 
58 TSTB 
59 BLT 
© éo EXIT$sS 
Si ’ Error code 
62 ERR12 [DIRERR 
63 ERR2? DIRERR 
64 ERR33? DIRERR 
65 ERR4?  IOERR 
66 “END 
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#REC § Receive by reference 

y and mae 
ERR2 + Hranch om error 
#14600009RS § Set base address in 

3 region 
WOR+W.NLENs RS > Size of resiionm to RS 
#64. °R3 § Convert blocks to butes 
#IO.WVRs tS > #1 se s8tITOSRs sc RSyR3e#40> § Write 

+ data 

ERRS $ Branch on directive 

$ error 
IOSk § Check for I/0 error 
ERR4 § Branch om error 


“ERROR CREATING 
ERROR ON RECEIVE AND 
ERROR ON WRITE QIO> 
#I0SKRs<ERROR ON WRITE QI0> 
START 


VIRTUAL ADDRESS WINTOW> 
MAF 


Example 8-5 Receive-by-Reference (Sheet 2 of 2) 
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The Mapped Array Area 


If you want to automatically set up a. large core resident 
data area, without uSing a create region directive, you may use 
special techniques to set up an area called a mapped array area. 
Figure 8-3 showS a task using a mapped array area. The Task 
Builder sets things up so that when the task is initially loaded, 
the task region is larger than normal, with the mapped array area 
set aside in memory immediately below the task header. 


The task is automatically attached to the region, since it is 
part of the task region. Therefore, all you have to do is to 
create a virtual address window and map it to the region. The 
area may be any size, as long as the task image and the mapped 
array area fit into the partition. This means that it may be 
larger than 32K words. 


Typically, the virtual address window maps only a portion of 
the region at atime. In Figure 8-3, the virtual address window 
maps 4K words at a time. 


This technique is used to implement virtual arrays in 
FORTRAN. Since the area isn't set aside until the task is loaded 
into memory, any initialization of the area must be performed at 
run time. 


Use the following procedure to create a task which uses_ the 
mapped array area. 


1. Set up a separate Psect in the source code and _ reserve 
space for the virtual address window (uSing .BLKB or .BLKW 
statements). Also set up symbols for reference, if 
desired. Do not initialize any locations. 

2. In the code, create a virtual address window. 

3. Map the window to a portion of the region. 

4. Later, map to other portions of the region by modifying 


the offset within the region and reissuing the map 
directive. 
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5. Task—-build with the WNDWS and the VSECT options. 


WNDWS=n allocates space in the task header for the 
extra window block 


VSECT=psect-—name:base:window-length:physical- length 
where 


psect-name = the name of the psect to be used _ for 
the virtual address window 


base = the base virtual address for the window 
window-length = the length of the window in bytes 


physical-length = the length of the mapped array 
area in 32-word blocks. 


This option sets up virtual addressing for the region 


and specifies the amount of space to be set aside for 
the mapped array area. 
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PHYSICAL 
MEMORY 
VIRTUAL 
MEMORY 
(4K WORDS) 
160000 APR 7 
APR 6 
APR 5 
ae IMAGE 
(28K WORDS) 
APR 3 
APR 2 
APR 1 
APR O HEADER & STACK 


1) INITIAL LOAD AND MAP 


MAPPED 
ARRAY 
AREA 


(32K WORDS) 


@) TOTAL SPACE INITIALLY \ 
ALLOCATED. 4K WORD 
AREAS MAPPED AS 
NEEDED. 


TK-7739 


Figure 8-3 The Mapped Array Area 
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Example 8-6 shows how to create and use a mapped array area. 
The following notes are keyed to the example. 


09e0e 8 68 


This program uses the supplied macro DIRERR. 


WNDWS = 1 is needed to reserve space for the extra window 
block. The VSECT option sets up addressing for Psect VV, 
beginning at virtual address 169900(8), for a length of 
20000(8) bytes or 4K words. The last argument sets up a 


mapped array area 200% 32-word blocks = 2@@@09(8) bytes 
long = 32K words. 


Set up Psect VV, which is used for mapping the mapped 
array area. Symbol A marks the beginning of the window at 
virtual address 160900(8). The number of bytes’ reserved 
must be at least as long as the window size (4K words). 
Data to be placed in the mapped array area. : 


WDB for the window. The region ID is left '@' because the 
region is the task region, which always has region ID Q@. 


Create the virtual address window and map starting at 
offset @, to the first 4K word area. 


Move "A1G7" into the first two words of the area. 


Modify the offset in the region in the WDB (at offset 
W.NOFF) to 290@(8) blocks, so that mapping will begin at 
that offset within the region. 

Map to the second 4K word area. 


Move "B2G7" into the first two words of the second 4K word 
area, 


Similarly, map and move "C3G7" to the third 4K word area, 
and "D4G7" to the fourth 4K word area. 


Map back to the first 4K word area. 
Display the first four bytes. 


Map to the second 4K word area and display the first four 
bytes. 
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@ map to the fourth 4K word area and display the first four 
bytes. 


@® Map to the third 4K word area and display the first four 
bytes. ° 


The mapping order for displaying the data is different just 
to show that the order need not match the original order for 
placing the data into the region. 


Now do the Tests/Exercises’' for this module in the 
Tests/Exercises book. They are all lab problems. Check your 
answers against the solutions provided, either the on-line files 
(which should be under UFD [202,2]) or the printed copies in the 
Tests/Exercises book. 


If you think that you have mastered the material, ask your 
course administrator to record your progress on your Personal 
Progress Plotter. You will then be ready to begin a new module. 


If you think that you have not yet mastered the material, 
return to this module for further study. 
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«TITLE VSS 
eIQENT 7017 
eENABL Le > Enable lower case 


+ 


This Frogram uses the marred array area. It rleces 
data im the first 2 words af each af the first four 
48 word blocks. It then retrieves the data and erints 
it at the terminal. 


SCN & Ch GRR 


10 Assemble and task-build instructions? 
MACRO/LIST L&C sy LIPROGMACS/LIBRARY sdevi CufdIVs3 
LINK/MAF/OP TIONS VS3SsFROGSUBS/LIBRARY 
Qetion? WNIWS=1 
Qetian? VSECT=UV 21600003 2000022000 
Oetiaon? <RETS 


SP "SS > “EY “HP “> “WY “E> “E> SP Mh > “> “ey 


18 *MCALL QTOWSSeEXITéS sWORBKRS oe CRAWSS » MAP SS 
19 * System macros 
@ 20 WMCALL  TLTRERR } Supplied macro 
el »PSECT VY CON? GEL... i Fsect for marred array 
2) ae $ 8 8res 
23 As eRLAE 20000 § Used to reference the 
24 § virtual area 
ao ePSECT * Back to blank Poect 
26 QATAZ *ASCIIT /AL/ 
2? ATE? *ASCIT /B2/ 
© 28 ATC? eASCII /C32 
29 NATION ASCII 7/47 
30 ATG? *ASCIIO /G7/ 
31 * Tlefine window definition block 
4 | 32 WIR? WORBKE 72009090200 cWS. MAF IWS WRT 90 
33 START! CRAWSS #WIik * Create window and mas 
34 § to ist 4KW block. 
35 BCC Al > Branch om dir ob 
346 NIRERR <ERROR CREATING WINtOW OR ON FIRST MAF 
37 ALS MOV NATAsA > Move data to ist word 
@| :: MOV #29 RS 
3f MOV NATGy»yACRS) + Mave data to 2nd word 
° | 40 MOY WINE » RO 
41 MOV #200eW.NOFF CRO) ¢ Set ur nmext 4KhW block 
42 MAF SES #W0E ¢ Mare 2nd 4K block 
43 RCC A4 § Branch om dir ok 
44 QIRERR ERROR ON IST MAF TO 2Nt 4KW BLOCK: 
o| * A4t MOV LATE yA 
4S MOV NATGsACRS) 


Example 8-6 Use of the Mapped Array Area (Sheet 1 of 2) 
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AZ: 


ABE 


AP: 


ALO? 


ALL? 


Pairs 


ZRUN VSS 
AlG? 
R267 
n4ac? 
C3G? 


Example 8-6 


Session 


MOV 
MAF SS 
BCC 
QNIRERR 
MOV 
MOV 
MOV 
MAF ES 
BCC 
QNIRERR 
MOV 
MOV 
MOV 
MAF #S 
RCC 
NIRERR 
QIOWSS 
MOV 
MAF SS 
ECC 
NIRERR 
QIOWSS 
MOV 
MAF SS 
BCC 
HIRERR 
QLOWSS 
MOV 
MAF SS 
RCC 
QIRERR 
QIOWSS 
EXITéS 
«ENT 
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#400eW.NOFF CRO) 3$ 
#WIE 
A? 
ERROR 
NATC +A 
ATG» ACRES) 
#GOOeW.NOFF CRO) ¢ 
#W0E 

A8 

XERROR ON IST MAF 
VATIUA 

NATGrACRS) 
#OeyW.NOFF CRO? 3 
WOK 

A? 3 
ERROR ON 2@NT) MAF 
#IOCWV Ro #5 ety op vot 
#F2OO0yW.NOFF CRO) 3 
HEWES 

ALO 3 
ERROR ON 2NI MAF 
FIO .WVER ey #5 9 #t yyy ot 
HSQ00eW.NOFF CRO) 3 
WIE 

ALi r] 
<ERROR ON 2NDT MAF 
#TO.WVBy #5 othe ee ot 
#4009W.NOFF CRO) ¢ 
WIE 

AL2 3 
ERROR ON 2ND MAF 
TO WVBR #5 9 bl yy yo 


¥ 


ON 1ST MAF 


START 


Seto our 3rd 4K block 


TO SRO 4KW BLOCKS 


Setour 4tn 4K plock 


TO 4TH 4KW BLOCK? 


Go beck to 
Rranch om dir ok 
TO 1ST 4KW BLOCK? 
Ay #4 s #40 

Go to @nd 4K block. 


Branch om dir ok. 
TO 2NT 4khW BLOCK? 
Ay #4 e #40 

Go to 4th 4h block 


Branch om dir al 
TO 4TH 4KW BLOCKS 
$A’ EA» FAO 

Go to 3re 4K block 


Branch om dir ok 
TO SRO 4khW BLOCK> 
Ay £4 9 F4AQ™ 

Exit 
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INTRODUCTION 
The RSX-11M file system is composed of three parts. 


e File structures - the organization and data structures 
maintained on the mass storage volumes themselves 


e Ancillary Control Processors (ACPs) - tasks which maintain 
the file structures and provide access to them 


e File access routines - provide user-written tasks with an 
interface to ACPs, which provide and maintain organization 


within files. 

This module reviewS some basic information about file 
Storage, and provides general information about the RSX-11M 
primary file structure called FILES-1l1, and its ACP. This module 
also presents an overview and comparison of the two supplied file 
access subsystems, File Control Services (FCS) and Record 


Management Services (RMS). The following module provides details 
on programming usSing FCS, which is the more widely used subsystem. 


OBJECTIVES 


1. To describe the steps involved in file I/0 


2. To describe the FILES-11 structure and how the FJ1ACP 
Maintains that structure during file I/0 


3. To identify the advantages of using either FCS or RMS for 
file access. 


RESOURCES 


1. IAS/RSX-11 I/O Operations Reference Manual, Chapters 1 and 
5 


2. RMS-11 User's Guide 
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OVERVIEW 


Quite often in an application you need to store data on a 
peripheral device (disk, magtape, etc.) for later retrieval. To 
write such an application, you must know something about’ the 
different devices which are on your system. In addition, you must 
understand the file structure and its support systems. Once you 
know that, you can learn the procedure for actually performing I/0 
operations. | 


TYPES OF DEVICES 
Record-Oriented Devices 
Record-oriented devices have the following characteristics. 


e Data is handled a record at a time. 
e There is no file structure, 


Terminals, line printers, and card readers are all 
record-oriented devices. They are not designed for storage and 
fast retrieval of data, but are designed instead to support 


interactive sessions or provide hard copies of reports and other 
data. 


File-Structured Devices 


File-structured devices have the following general 
characteristics. The data they contain: 


e Can be handled in files 
@e Can be stored and retrieved quickly 


e Is typically stored on a storage medium which can be moved 
from one device to another. 


Hard disks, floppy disks, and magtape are examples of 
file-structured devices. The following definitions should prove 
helpful in our discussion. 


a file - a collection of related data; therefore, a 
logical unit of mass storage. | 
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volume - a physical unit of mass storage consisting of a 
recording medium and its packaging. Examples are a disk 
pack, a reel of tape, a diskette, and a DECtape MII 
cartridge. 


of File-Structured Devices - There are two types of 


file-structures devices, sequential and random-access. The type 
is determined by the kind of access to data on it. 


Sequential devices have the following characteristics. 


Data is retrieved in the same order as written 


New data iS always appended at the logical end of the 
tape, after the last data written . 


data cannot be written in the middle of the volume without 
losing the data past that point. 


Magtape and cassettes are examples of sequential devices. In 


essence, 


data is stored in order as written. To access any data, 


all data before it on the tape must be read first. 


Under RSX-11M, the magtape ancillary control processor 
(MTAACP) supports the ANSI file structure. 


The MTAACP supports the following file setups: 


A single file on a single volume 
A single file on multiple volumes 
Multiple files on a single volume 
Multiple files on multiple volumes 


Random-access devices, also called block-structured devices 
or block-replaceable devices, have the following characteristics. 


They can: 
e Store and retrieve data in units called blocks 
@e Write or read blocks in any order 
@e Rewrite blocks without interfering with other blocks. 


Hard disks (RL@1/02, RP@6, RM@2/03), diskettes (RX11, RX211) 
and DECtape II are examples of random-access devices. 
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The FILES-11 file structure, the standard RSX file structure, 
is supported by the FILES-11 ancillary control processor (FI11ACP). 
FI1ACP supports multiple files on a volume, but a file may not 
extend across volumes. The COPY command (PIP in MCR) maintains 
the FILES-11 structure during transfers of files within a given 
‘device and between FILES-1]1 devices on a system. 


The ANSI file structure is useful for transfers of files 
between different (possibly non-DIGITAL) systems. FILES-11 is 
useful between DIGITAL systems under RSX-11M, RSX-11M-PLUS, IAS 
and vMS if the two systems have a device in common (e.g., both 
systems have RL@2s). The FLX utility is provided to facilitate 
transfers between RSX and other DIGITAL systems which don't 
Support FILES-l11, or between systems which support FILES-ll (even 
between two RSX-11M systems) which do not have a common FILES-11 
device. In that case, the FLX transfer is typically made on 
magtape, using DOS or RT-11 format. 
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COMMON CONCEPTS OF FILE I/O 


Common Operations | 
File I/O is often used to perform the following operations. 
e Creating a file 
e Deleting a file 
e Modifying existing data within a file 


e Appending new data to a file (or extending the file). 


Steps of File 1/O 
Use the following three basic steps to do file I/O. 
1. Open the file. 
Specify a LUN and the file. The ACP connects ae task 
LUN to the file. Specify the access rights desired. 
The ACP checks against the file protection code. If 


you are creating a new file, specify the file 
characteristics (e.g., format and initial length). 


2. Perform the I/O operations. 


Use macros to invoke subroutines to store data in the 
file and/or retrieve data from the file. 


a Close the file. 


Notify the system that the file operations are 
completed, so that appropriate cleanup work can be 


performed. 
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FILES-11 


In order to use FILES-1l, you need to understand its 
structure and how to interact with it. 


FILES-11 Structure 


A block is the smallest unit of storage which is read from, 
or written to, a FILES-11 device. Typically, the blocks are 
256(18) words or 512(10) bytes long. Some devices divide or 
format their volumes into pieces which are 256(18) words long, and 
others do not. Therefore, the FILES-l11 structure does some 
converting or mapping so that you work with logical blocks which 
are all standard size. When the volume is’ formatted, logical 
block numbers are assigned to each 256(1@) word area on the disk, 
starting with logical block @. Generally, the position of data on 
a FILES-11 volume can be described in three alternate ways, by: 


e Physical location 
@ Logical block number 
@e Virtual block number 


Table 9-1 compares the three ways. Figure 9-1 shows an 
example of the mapping among the different methods. Typically, 
you will reference data only within files. The files are 


referenced by virtual block numbers within the file, starting with 
1. Logical block numbers are assigned to the entire disk, 
Starting from @. 


The system converts virtual block number’ references’ to 
logical block number references. For example, if you request a 
read of virtual block 5, the system looks at the mapping and finds 
that this corresponds to logical block 1622(8). This logical 
block, in turn, is mapped to one or more specific sectors on _ the 
disk, which are read from the disk. 
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Table 9-1 Comparison of Physical, Logical and Virtual Blocks 
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Typically, data is accessed as records, units which are not 
exactly one block or 512(18) bytes long. A record is a unit of 
user specified size, corresponding, for example, to a single bank 


account or a single line of text at a terminal. 


Figure 9-2 shows how the operating system handles a request 
to read a record using FCS. The first. row shows a FORTRAN READ. 
The FORTRAN READ instruction is converted by the compiler to a 
GETS call to the File Control Services (FCS) to read that record. 
In MACRO, you will issue the GETS call yourself. FCS checks’ to 
find out which virtual block within the file contains that record 
and issues the QIO directive for you. The Executive converts’ the 
virtual block number to its corresponding logical block number and 
issues a read logical block QIO. The driver then converts’ the 
logical block number to the appropriate physical locations, and 
reads a block of data into memory. The record itself will then be 
located within the block of data. 


The second row shows ‘a BASIC-PLUS-2 READ under the Record 
Management Services (RMS). The BASIC-PLUS-2 compiler converts the 
READ to a RMS SGET call. ° RMS converts this to a QIO, to read _ the 
corresponding virtual block. From that point on, the steps are 
just like those in the FORTRAN example. 
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FILE SAMPLE.TXT;1 
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Figure 9-] Example of Virtual Block to Logical Block, 
to Physical Location Mapping 
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Figure 9-2 How the Operating System Converts Between 
Virtual, Logical, and Physical Blocks 


Figure 9-3 shows the FILES-11 structures which are used to 
Support virtual-to-logical block mapping. Every FILES-11 volume 
has a number of system files on it, one of which is the Index File 
(INDEXF.SYS). The Index File contains certain blocks which are 
for system use, plus a file header block for each file on the 
volume, 


Each file header block contains file retrieval pointers which 
are used in mapping virtual blocks to logical blocks. Each file 
retrieval pointer locates a range of contiguous logical blocks. 
The first byte tells how many contiguous blocks are in the group, 
and the next three bytes specify the logical block number of the 
first block in the group. Therefore, in the figure, there are 
five contiguous blocks, starting with logical block 336851(190). 
Virtual block 1 = logical block 336851(18), vb 2 = 1b 336852(10), 
vb 3 = lb 336853(18), vb4 = 1b 336854(10), and vb 5 = Ib 
336855(18). The next group of blocks, starting with virtual block 
6 has 51(1@) blocks and begins at logical block 336989(18) up — 
through logical block 336950(10). The last 17(190) virtual blocks 
(virtual blocks 57(18) to 73(18)) begin at logical block 
337986(18) up through logical block 337922(190). These file 
retrieval pointers are updated each time a change in_ block 
allocation occurs as a result of a file I/O operation. 
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Figure 9-3 FILES-11 Structures Used to Support 
Virtual-to-Logical Block Mapping 
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Directories 


The operating system identifies files by file IDs, which are 
used to calculate the location of the file header within the index 
file. When you need to locate a file, it is difficult to remember 
where it is on the disk, or even what its file ID is. Instead, 
you use a file specification, a more English-like way of 
identifying a file. An example of a file specification is: 
DR1:[5,6]SAMPLE.TXT;1. Tasks you write also usually identify 
files with a file specification. Directories are structures set 
up on a FILES-11 volume that are used to group files together, and 
to convert file specifications to file IDs. 


A directory is a list of files belonging to a single user, or 
grouped together for other organizational purposes. An example of 
files grouped together for organization is the libraries in User 
File Directory (UFD) [1,1] on the system device. Ona FILES-11l 
volume, a directory is a special file containing a list of the 
files belonging to that user or group. For each file, the list 
has: 


e The file specification: name, type, and version number 
e The file ID 


The file ID consists of a file number and a sequence number. 
The file number identifies the offset within the index file to the 
virtual block containing the file's file header. The sequence 
number is used to distinguish this file from previously deleted 
files which used the same file header. There are two levels of 
directories on a volume, as follows. 


@e One Master File Directory (MFD) which is directory [9,98] 
@e One or more User File Directories (UFDs) 


Figure 9-4 shows the relationship between the two levels’ and 
the files. The MFD contains a list of the system file, plus one 
entry for each UFD on the volume. Each UFD file has a name of the 
form gggmmm.DIR, where [ggg,mmm] is the user identification code 
(UIC) of the owner. Each UFD contains a list of the files in that 
directory. . : 
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MFD 
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UFD UFD 
[200,1] [303,5] 


HIYA.MAC;1 FLY.TXT;1 IZZY.TXT;1 OZY.TXT;1 LOGIN.CMD;1 
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Figure 9-4 Directory and File Organization on a Volume 


Figure 9-5 shows the steps used in locating and accessing the 
blocks of the file DR2:[5,6]SAMPLE.TXT;1. The device name, DR1: 
tells which device or volume to look on. The operating system 
reads the MFD file header to find the retrieval pointers for the 
MFD file itself. It converts the virtual blocks to logical blocks 
and reads the blocks of the MFD file. It searches through the 
directory list for the UFD [5,6], namely the file 9959906.DIR. 


When it finds that name in the list, it uses the file ID to 
locate the UFD file header. It reads the retrieval pointers 
there, converts the virtual blocks to logical blocks, and _ reads 
the blocks of directory bo: 76.6 It looks for an entry 
SAMPLE.TXT;1. When it finds that entry, it uses the file ID _ to 
locate the SAMPLE.TXTs file header. It then reads the retrieval 
pointers in the file header, converts’ the virtual blocks’ to 
logical blocks, and reads the blocks of the file itself. 


If this sounds like a lot of work, it is. Later, you will 


learn about a way to go directly to the file header using the file 
ID if it is opened a second time during a task's execution. 
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a File on a FILES-11 Volume 


FILE I/0 


Five Basic System Files 


There are five basic system files found on all FILES-11 
volumes, They are all created when the volume is initialized and 
are all entered in the MFD. Two of these, the Index File and the 
Master File Directory, have been mentioned previously. The five 
files and their purposes are as follows. 

e The Index File: INDEXF.SYS. 

- Boot block - used when a system volume is bootstrapped 


- Home block - contains volume identification and other 
information 


- Index file bitmap - a record of which header blocks 
are in-use; used by F11ACP when allocating header 
blocks to files 


- File header blocks for all files on the volume 


e The Storage Map: BITMAP.SYS. 


- A record of which blocks on the volume are in use 
- Used by FI11ACP when allocating blocks to files 
e The Bad Block File: BADBLK.SYS. 
- A list of blocks on the volume known to be bad 
e The Master File Directory: 9%@@000.DIR. 
- Entries for the five system files 
- An entry for each UFD file 
e The System Checkpoint File: CORIMG.SYS. 


- Space used for checkpointing if the system manager 
allocates space in it. 
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Functions of the ACP 


The FIIACP maintains the FILES-l11 Structure on a_e volume 
during its use. 


The most elementary functions performed by the ACP are as 


follows. 


e Maintaining the File Header Blocks. This includes: 


Allocating and initializing a file header when a_ file 
is created 


Recovering a file header for reuse when a file is 
deleted 


Maintaining file attributes such as protection code, 
length, etc. 


Maintaining the file retrieval pointers 


e Maintaining directories. This includes: 


Creating directory entries when a file or UFD is 
created, or when a file synonym is created (e.g., by 
the PIP /EN switch) 


Removing entries from directories when a file is 
deleted or a file synonym is removed (e.g., by the PIP 
7RM switch) 


e Maintaining block allocation. This includes: 


Allocating blocks to files when a file is created or 
ex tended 


Recovering blocks for reuse when a file is deleted or 
truncated 


e Controlling and facilitating task access to files. This 
includes: 


Checking protection codes to determine access rights 


Connecting a task's LUN to a file to allow virtual 
block I/0 | 


Controlling shared access to files. 
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Figure 9-6 shows the flow of control during the processing of 
an I/O request. This figure parallels Figure 9-2, which shows how 
the operating system converts virtual blocks to logical blocks’ to 
physical locations. 


The user task issues a read record request which is converted 
by an FCS routine in the user task to a QIO, to read a virtual 
block. The Executive converts the virtual block number to a 
logical block number, using file retrieval pointers in pool. 
These retrieval pointers are built by F1l1ACP from the retrieval 
pointers in the file header. The Executive issues a read logical 
block request to the driver. The driver converts the logical 
block number to the actual physical locations and copies the block 
into the user buffer. 


For additional information on the FILES-11 structure, see 
Chapter 5 of the IAS/RSX-11 I/O Operations Reference Manual. 


USER TASK POOL 
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DRIVER 
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Figure 9-6 Flow of Control During the Processing of an 
I/O Request 
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OVERVIEW AND COMPARISON OF FCS AND RMS 


Common Functions 


The File Control Services (FCS) and the Record Management 
Services (RMS) both offer easy methods for performing file I/O. 
The operator or programmer need not be concerned with all_ the 
nitty-gritty details, but can instead let FCS or RMS take care of 
them. Both perform the following functions: 


e Serve aS an interface to the ACPs 


e Allow I/O to the virtual blocks of ae file on a 
block-by-block basis (Block I/O) 


e Divide files into logical records and allow MI/0 to 
individual records within a file (Record I/O) 


e Allow the programmer to process records uSing one of the 
following buffers (Figure 9-7) nn 


- A buffer reserved by the programmer with another 
buffer transparently used by FCS or RMS (move mode) 


- Directly in the buffer used by FCS or RMS (locate 
mode) 


e Allow device independent I/O - the routines are written to 
work correctly with terminals, disks, etc. 


e Provide mechanisms for controlling shared access to files. 
Beyond that, FCS and RMS each offer a variety of file 


organizations, record types, and access modes. These are 
described in the following sections. 
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Figure 9-7 Move Mode and Locate Mode 
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FCS FEATURES 


File Organizations 


Essentially, all FCS supported files are sequential, meaning 
that new records are added at the end of the file, and records are 
stored in the order they are written. Figure 9-8 shows a file 
with sequential organization. 


END OF FILE 


RECORD | RECORD |RECORD]| ,,, | RECORD 
1 2 3 n 


SEQUENTIAL FILE ORGANIZATION 


Figure 9-8 Sequential Files 


Supported Record Types 


FCS supports two record types, fixed-length records and 
variable-length records. Variable-length records may be sequenced 
or nonsequenced. An example of each type of file is shown below 
with the following three records: 


12345 
123 1234 
AAAA BBBB CC D 


The examples are in DMP format; the six-digit number on the 
left is the byte count in octal of the first byte in that row. 
Then 16(18@) = 20(8) bytes follow in order in octal. Below each 
byte in octal is its equivalent in ASCII. An underscore (_) 
stands for an ASCII blank. Consult the examples as you read _ the 
description of each record type which follows. 
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Examples: 


Fixed-Length Records (record length = 


OBBGHBS G61 B62 
1 2 
OBGG20 C48 xxx 
_ pad 
OBGG40 B40 940 


O90068 840 104 
D 


Variable-Length Records 


GB8000 885 BBB B61 B62 863 


863 
3 
G61 
1 
G48 


049 


G64 
4 
862 
2 
XXX 
pad 
840 
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G65 848 B48 648 
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G880820 B63 G64 B16 BBB 1681 
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3 
OBAG4G C40 104 xxx xxx xxx 
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Sequenced Variable-Length Records 


OBO0GH BH7 BBG BH1 BBB B61 B62 863 
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Fixed-—length records all contain the same number of bytes. 
Therefore, the location of the beginning of any record within the 
file can be computed from its record number. With all record 
types, each record begins on an even word boundary. This means 
that in files with fixed-length records, if each record contains 
an even number of bytes, the next record begins immediately after 
it. If, on the other hand, each record contains an odd number of 
bytes, one byte is unused after each record, and the next record 
begins at the next word boundary. This unused byte is called a 
pad byte. 


Variable-length records may each have different lengths. For 
all files with variable-length records, the first word of each 
record contains a byte count, telling how many bytes are in that 
record. For variable-length nonsequenced records, this count word 
is followed by the data itself. 


Following this, at the next word boundary, is the byte count 
for the next record and then its data. To locate a given record 
within the file, you must first read the byte count for the first 
record in the file. You can then use the byte count to locate the 
second record. You then continue reading byte counts and locating 
successive records until you reach the desired record. 


Variable-length sequenced records contain a byte count, a 
user specified sequence word, and then the data itself. The 
sequence word can contain the record number or any other user 
specified value. Variable-length sequenced records are not used 
much under FCS. They are supported to allow compatibility with 
RMS variable-with-fixed-control records. 
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Table 9-3 compares the different FCS record types. 


Table 9-3 Comparison of FCS Record Types 
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Record Access Modes 


FCS offers two record accesS modes, sequential access_ and 
random access. Table 9-4 compares the two access modes. The 
major difference is that with random access, the uSer can process 
records in any order (e.g., record 12, then record 4, then record 
29). This is possible with fixed length records only, because FCS 
can calculate the position of each record within the file from the 
record number and the record size. 


With variable-length records, on the other hand, FCS can't 
locate record 12 unless it reads records 1 through 11 first, using 
the record length in the first word of each record to calculate 
the starting position of the next record. Therefore, you must use 
sequential access with variable length records. You may choose 
either of the two access modes for fixed length records, depending 
on how your application processes the records. 
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Table 9-4. Comparison of Sequential Access I/O and 
Random Access I/0 
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File Sharing 


A task which opens a file may choose one of the _ following 
options: 


e That no other accessor change any data in the file while 
it has access ("sShared" read, “exclusive” write). 


- If this task desires read access, other accessors may 
have simultaneous read access, but no other accessor 
may have simultaneous write access. 


- If this task desires write access, no other accessor 
may have simultaneous read or write access. 


- Any access request cauSing a conflict is rejected. 


@e That other accessors may change the data while it has 
access ("Shared" read/write access). 


- If this task requests read or write access, other 
accessors may have simultaneous read or write access, 


- Use extreme care - Any precautions against corrupted 
data are the responsibility of the accessors. 


e That no other accessor changes any block within the file 
which has already been accessed (block locking). Shared 
access to the file is allowed, but: 


- Bach block which is written to is locked for exclusive 
write access. . 


-~ Fach block which is read is locked for shared read 
access. 


- It is not recommended if accessing a large numbers of 
blocks, because each block lock uses four words of 
pool. 


- Any attempt to access a block which causes a conflict, 
returns an error. 
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RMS FEATURES 


File Organizations 


RMS supports three file organizations, sequential, relative 
and indexed. See Figure 9-9. Sequential files under RMS are the 
Same as sequential files under FCS. A relative file is composed 
of a series of cells of uniform size. The cell size is greater 
than or equal to the largest record to be placed in the file. A 
Single record may be written to a cell, or the cell can be empty. 
The cells may contain variable-length records. Variable-length 
records within relative files can be accessed randomly because 
each record is contained within a fixed-length cell. Also, when 
you read successive records in a relative file, empty records are 
automatically skipped. 


An indexed file is composed of records, plus one or _ more 
indexes which are used to access those records. Each index is 


used to retrieve records according to the contents of a particular 
field, or key, within the record. The data records themselves are 


ordered according to a primary key which you declare when you 
create the file. 


Figure 9-9 shows an indexed file with a single key, namely 
last name. In the example, the data records are in the bottom 
row, ordered alphabetically by last name. The index for this file 


contains two other levels, level 1 and level 2 (the root level). 


A search for a record begins at the root level. For example, 
to find the record with key value FRANCIS, search through the root 
level, checking for the first value which is greater than or equal 
to FRANCIS. The first such value is SMITH. Go to the next level 
and again search for the first value greater than or equal _ to 
FRANCIS; it is GROSS, the first value. Now go to the next level 
and search again; this time the value FRANCIS is’ found. Since 
this is level 9, we have found the record. 


AS new records are added to the file, they are inserted in 
order at level @ of the primary index. The primary index 
structure is adjusted for the new entry at the same time, In 
addition, any alternate index structures for other keys are 
adjusted as well. There is always one primary key, and there may 
be aS many as 254(10) alternate keys. 
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Figure 9-9 RMS File Organizations 


Level @ of the alternate keys contains pointers to. the 
original location of the data record itself. If a data record is 
ever moved in order to maintain the index structure, a pointer is 
created and maintained in the records original location, which 
points the data record's new location. 


One specific advantage of an indexed file over ae_e relative 
file is that an indexed file allows you to search for records 
using several different key fields, while only the cell number can 
be used with relative files. Even with a single key, indexed 
files offer keys consisting of any ASCII characters, in contrast 
to just a cell number for relative files. 


There is, of course, more space overhead required in the file 
for the index structures. In addition, more execution time is 
required to insert new records, because the index structures must 
be updated as well. We are keeping things rather simple in the 
discussion here. For additional information, see the 
RMS-11 User's Guide. 
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Record Formats 


RMS supports three record formats; fixed-length records, 
variable-length records, and variable-length records with fixed 
control. Fixed-length records and variable-length records are the 
same as fixed-length records and nonsequenced variable-length 
records respectively, under FCS. They are both supported under 
all three file organizations. 


variable-length records with fixed-control (VFC) contain a 
fixed-length portion, for control, followed by a variable-length 
portion. The fixed control portion may be up to 255(1@) bytes 
long. A sequenced variable-length record under FCS is the same as 
a VFC record with a 2-byte (one word) fixed control portion. 


An example of the use of VFC records is a bank account file, 
where some accounts have both savings and checking, and others 
have just one or the other. The fixed control portion could 
contain the account number plus’ an indication of the kinds of 
accounts contained in it. The variable portion contains’ the 
account information for those accounts. The length of this 
portion varies, depending on how many accounts the person has. 
VFC records are supported under sequential and relative file 
organizations only. 


Record Access Modes 


RMS supports three record access modes: sequential access, 
random access, and access by Record File Address (RFA). 
Sequential access and random access are similar to the FCS access 
Modes, except that they are applied differently for indexed files. 


For sequential access on an indexed file, the "next" record 
is the record with the next highest key value using the specified 
key, not the next record added to the file. For random access, a 
key value for a certain key is specified, and that record is 
located and accessed. To access a record-by-record file address, 
save pointers to the record (called its record file address or 
RFA) from one access, then use the pointers to subsequently access 
the record again. 


Table 9-5 describes the various access modes supported for 
each file organization and how they work. For additional 
information, see the RMS-1] User's Guide. 
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Table 9-5 File Organization, Record Formats, and Access Modes 
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File Sharing Features 


RMS offers more sophisticated file-sharing options than FCS. 
Sequential files can be shared for read access only. Relative and 
indexed files can be shared for read and write access. When 
opening a relative or indexed file, a task indicates one of the 
following options. 


@e No other accessor can change data in the file while it has 
- access ("Shared" read, exclusive "write"). 


e Other accessors can change data, but subsets of the file 
are protected at a time, while in use. 


Relative and indexed files are divided into units’ called 
buckets (of user specified size, each ] to 32(1@) blocks long). 
In fact, all actual I/O tranfers are performed on full buckets 
only. In implementing protection of subsets of the file at a 
time, protection is on a bucket-—by-bucket basis (bucket-locking). 


A bucket is locked from the time any task with write access 
accesses a_record in a bucket, until that task begins operations 
on another bucket, or closes the file. This means that records 
within a given bucket can't be accessed by other tasks while 
another task with write access is using the bucket, But other 
tasks may access other buckets in the file during that time. 
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Table 9-6 Comparison of FCS and RMS (Cont) 
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Now do- the tests/exercises. for this module in the 
Tests/Exercises book. They are all written problems. Check your 
answers against the provided solutions in the Tests/Exercises 
book. 


If you think that you have mastered the material, ask your 
course administrator to record your progress on your Personal 
Progress Plotter. You will then be ready to begin a new module. 


If you think that you have not yet mastered the material, 
return to this module for further study. 
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FILE CONTROL SERVICES 


INTRODUCTION 


The File Control Services (FCS) subsystem provides the means 
through which most tasks perform file I/0. You make calls 
directly to the FCS routines. 


This module introduces you to the structure of FCS, the 


services it offers, and the ways in which you can use those 
services. 


OBJECTIVES 


1. To choose file characteristics for a specific application, 
then create a file with those characteristics 


2. To write tasks which read or write data using record I/0 
or block I/O (MACRO only) 


3. To identify and implement methods of optimizing file I/O. 


RESOURCE 


e IAS/RSX-11 I/O OPERATIONS MANUAL, Chapters 1, 2, and 3 
(Additional reading - Chapters 4 and 6) 
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REVIEW OF FILE I/O 


Use the following basic steps to perform file I/O. 
1. Open the file. 
e Ask ACP to connect LUN to file. 
e Specify access rights desired (RWED). 
e Specify type of access. 
- Block I/0 or record I/0 
- For record I/O only 


Random or sequential access 
Move or locate mode 


e If new file, specify file characteristics. 
- Record type 


- Record attributes 
- File initial size and extend size 


2. Perform the actual I/O operations. 


oo Close the file. 


e Perform any needed clean-up work. 
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INTRODUCTORY EXAMPLE 


We begin our discussion of FCS with an example. The purpose 
is to give you a feeling for how to perform the basic steps of 
file I/O. After that, we will examine the data structures 
involved, and the specific steps for setting them up and using 
them to perform file I/O. 


Example 10-1 creates a file with variable-length records 
using sequential access. The records are input from TI: and then 
placed in the file. The following notes are keyed to the example. 


& The interface with FCS is through system macros. 


@ FCSERR is an error message macro supplied with this 
course, Its source and documentation concerning its use 
are in Appendix A. It is used here to avoid having to 
worry about the details of the code. 


@ The FSRSZ$ macro reserves space in the user task for a 
general FCS data area which is called the file storage 
region (FSR). This macro must be issued in every program 
that uses FCS. 


(4 A file descriptor block (FDB) contains data structures for 
a file opened by FCS. A Separate FDB is required for each 
file which is open at the same time. The FDB and its 
related data structures can be filled in at assembly time 
or at run time. In this example, they are set up mostly 
at assembly time, which is more run time efficient. 


@ open the new file VARI.ASC. Notice that the run-time 
macro references the label of the FDB. This is necessary 
in the case of multiple FDBs, for multiple files opened by 
a Single program. 

6 ] Get input record from TI:. 


@ write (PUTS) the record to the file. For variable-length 
records, specify the record length in bytes. 


6 Branch on any FCS error. 
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Get next record. On a “Z, close the file and exit. 


On the Dump - A file dump is included for each example in 
this module which creates a new file. The dumps were 
created using the DMP utility, and are in octal byte 


format. Because this file has variable-length records, 
the first word in each record is a byte count for the 
record, See the section on FCS File Organizations in the 


File I/O module for additional information on the dump. 


423 


FOURS FOBIF $ 


FNAME? NMBLKS VART ASC 
BUFF? + BLKE B04 


FILE CONTROL SERVICES 


*TITLE CRESEQ 
eIQENT /01/7 


*ENABL LC y Enable lower case 


+ 


File CRESEQ.MAC 


records using seavential access. It reads 
ineut and. closes the file. 


Assemble and task-build instructians? 


~=CRESEQ 


“> <> > “> “Hh “> C> GP we KW Sr > “E> > 


i 


*MCALL EXST#CsQITOWSC»QTOWSsDIRS § Sustem 
eMCALL FSRSZ$eF TO BIFS»FPOATSASFIURCHA sy FOF SA 
FCS macros 


*MCALL NMBLAG*SOPENGWe PUTS »CLOSES § 5 


CRESEQ creates e file VART.ASC of variable-length 


Tits and elaces them in the file. A “Z terminates 


LINK/MAF CRESEQrsL BS tl» LIPROGSUBS/LIBRARY 


from 


MACRO/LIST LESlC1»s LIFROGMACS/LIBRARY vy devi Cufdd—- 


Mecros 


System 


»*MCALL CIRERR ys TOERRyFCSERR ¢ Suerslied macros 


bd 


FSRSZS$ il * 1 file for record I/0 


> Tefine file descrirtor block for VARTI.ASC 


“ar 


FOATGA R+VARYFILCR 


FORCHA  » RUFF 
defaults 
FOP SA dL» FNAME Use LUN dy» 


"VARTI.ASC" 


St “> Sh WP ‘Er SP CF SP “Ch SP Ge “SD 


IOST? + BLKW 2 
+EVEN 


Allocate the 

Variable lensth records: 

Listing - imrelied 

“CRS 9 LFS 

Seauential access and 
record I/0 by 


at FNAME 


User Record Ruffer 
I/O status block 


user record buffer 
file srec 


*ENABL. LSE § Enable local symbol 
§ block 
+ Oren file for writes call ERRI if oren fails 
START? OFENSW #FUI By y 99» xERRA 
§ Get record from terminals rut to file. 
103 QTIOWSC TO.RVBySelesTOSTs»<BUFF »80.> 
RCS ERR2Y § Branch on directive 
3 error 
TSTE IOST § Check for I/0 error 
BLT ERR2T * Branch om I/0 error 


Example 18-1 Creating a File in MACRO-11 (Sheet 1 of 2) 
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Q| 2 MOV TOST+2+R1 * Number of bytes ineut 
30 FUT $ #F 0K 9 Ri ¢ Fut record to file 
©. si RCS ERR3 } Branch on FCS error 
Os2 RR 10% § Get next record 
33 
54 EXIT? CLOSES #FDBR»yERR4 y Close file 
a ba EXST#C EX#SUC y Exit with success 
36 ys status 
37 § Error code ~ Close file if mecessary, disrelay error 
38 ¥ Messade and exit 
uF ERR1? FCSERR #F0Rs<ERROR OFENING FILE> 
40 ERR203 OIRERR <DIRECTIVE ERROR ON REALS 
61 ERR2T3 CMFE #IE «EOF » LOST $ Is it “Z? 
62 REQ EXIT + If eauals close file 
63 > and exit 
64 IOERR #TOST»<ERROR ON READS ¢ Diselay error 
65 3 messaste and exit 
66 ERR? CLOSES #FO0URsERR4 + Close file 
&7 FCSERR #FRRs<ERROR WRITING RECORD: 
48 ERR4 3 FCSERR #F0By<ERROR CLOSING FILES 
é9 +ENT START 
Rum Session? 
>RUN CRESEQ 
aie ae 
2eeRe 22 
33S 
JAZZ Jase JAZZ Jazz 
Have vou ever seen the sun? 
45 &6 &4& &4 
ae 
Tumse of DRI CSOSs 301 1VART.ASC#27 ~ File ID) 34772260 
Virtual block 07000001 ~ Size 312. butes 
000000 004 000 061 061 O61 O61 010 000 062 062 O62 062 062 040 
© 000020 003 000 063 063 063 000 023 000 112 101 132 132 0640 112 
000040 172 040 112 101 132 132 040 112 141 172 172 000 O33 000 
000060 166 145 040 171 157 165 040 145 166 145 162 040 163 145 
000100 040 164 150 1435 040 163 165 156 077 000 O13 000 0466 066 
000120 066 040 046 066 040 066 066 000 000 000 000 000 000 000 
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Creating a File 
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BLOCK BUFFER 


BLOCK BUFFER 


$$FSR1 
(BLOCK 
BUFFER 
POOL) 
BLOCK BUFFER 
$SFSR2 IMPURE DATA 


TK+7734 


Figure 1#-1 The File Storage Region 


426 


FILE CONTROL SERVICES 


USING FCS 
In this course, we cover many of the options supported by 
FCS. However, we cannot cover all of the options in detail. 


Therefore, it is very important that you read the reading 
references mentioned in the IAS/RSX-11 I/O Operations Reference 
Manual for further information. This is especially important if 
you are going to use an option which is not discussed in detail in 
this course. For a general discussion of FCS and its use, read 
Chapter 1 of that manual. 


Preparing to Open a File 


The File Storage Region (FSR) -- The FSR is an area allocated 
in your task as working storage for FCS operations. The FSR 
consists of two program sections which are always contiguous’ to 
each other. Figure 19-1 shows the layout of the FSR. The program 
sections and their purposes are as follows. 


SSFSR1 -- contains space for block buffers and the block 
buffer headers for record I/O operations. You determine the 
size of this area at assembly time with the FSRSZS macro. 
Block buffers and headers are allocated from this area when a 
file is opened for record I/O operations. Enough space must 


be allocated for the greatest need of your task at any one 
time. 


SSFSR2 -- contains impure data which is used and maintained by 
FCS when performing both record I/O and block I/O operations. 
The area is set aside at assembly time. Portions of it are 
initialized at task-build time; other portions are maintained 
by FCS at run time. 


The data flow during record I/0 operations for locate mode 
and move mode is shown in Figure 19-2. Note that blocks of data 
are transferred directly between the device and the FSR_ block 
buffer. In locate mode, you usually access the data directly in 
the FSR block buffer. In move mode, an additional transfer is 
made of the specified record between the FSR block buffer and a 
user specified buffer. 


The data flow during block I/O operations is different, as 
Show in Figure 19-3. Blocks of data are transferred directly 
between the device and a user specified buffer. No FSR block 
buffer is needed. 
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MOVE MODE 


TASK 
(IN MEMORY) 


USER RECORD 
BUFFER 


MOVE 
RECORD 


FSR BLOCK 
BUFFER 


MOVE 
BLOCK 
(IF NECESSARY) 


LOCATE MODE 


TASK 
(IN MEMORY) 


USER RECORD 
BUFFER 


FDB 


MOVE 
BLOCK 
(IF NECESSARY) 


FSR BLOCK 
BUFFER 


TK+7729 


Figure 18-2 Move Mode Versus Locate Mode for Record I/O 
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TASK 
(IN MEMORY) 


TK-8636 


Figure 19-3 Block I/O Operations 


Initialization of the FSR 


Use the FSRSZS macro to establish the size of the FSR at 
assembly time. This macro must be used in any program using FCS, 
whether for block I/O or record I/O. The format of the FSRSZS$ 
macro is as follows. 


FSRSZS$ fbufs,bufsize,psect . 
fbufs - for block I/0 only, specify ) 


- for record I/O or record and block I/0, maximum 
number of buffers needed for record I/0 


bufsize - total space needed for block buffers (in bytes). 
Defaults to fbuf*512(19) 
psect - return Psect if other than default. 
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Examples: 
FSRSZS @ 


Using FCS for block I/O only. Allocate FSR space for impure 
data only (SSFSR2). . 


FRSRSZS 2 


Using FCS, allocate FSR space for impure data (S$S$FSR2), and 
for record I/O block buffers (S$S$FSR1). Total allocation for 
block buffers in SSFSR1 is two headers plus 2%*512(19) = 


1924(18) bytes. 
FSRSZ$ 3,2048 


Using FCS, allocate FSR space for impure data (S$SFSR2), and 
for record I/O block buffers ($$FSR1). Total allocation for 
block buffers is three headers plus 2@48(1@) bytes. For 
example, two are 512(1@) bytes long and the third is 1924(1@) 
bytes long. 


The buffer size uSually corresponds to a disk block (512(19)) 
for disks, or the buffer width for terminals. If all record I/O 
operations use single buffering with the default buffer size of 1 
disk block (512(18)), then fbufs should be the maximum number of 
files open at the same time for record I/0. Bufsize can be 
defaulted to that number, times 512(10). 


If double buffering is used for some record I/O operations, 
or larger block buffers are desired (to reduce the number of I/O 
transfers), specify values for fbufs and/or bufsize. This allows 
for your maximum need for files open at the same time for record 
I/O. 


See section 2.6.1 on FSRSZS in the IAS/RSX-11 Operations 
Reference Manual for a discussion on how to calculate bufsize. 
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The File Descriptor Block (FDB) 


Functions of the FDB - The FDB contains information used by FCS in 
opening and processing a file. One FDB is required for each file 
that is open at the same time by your’ program. An FDB may _ be 
reused once the file associated with it is closed. The FDB is 


used by: 


e The task, to pass information to FCS 

e FCS, to return information to the task 

e FCS, for internal bookkeeping for the file. 

You must allocate space for each FDB and initialize specific 
portions, before opening a file. You may use either assembly-time 


or run-time macro calls. Figure 10-4 showS an FDB and its 
different parts. 


FILE DESCRIPTOR BLOCK 


FILE ATTRIBUTE RECORD TYPE AND SIZE 
SECTION FILE TYPE AND SIZE baie 


RECORD OR BLOCK BUFFER DESCRIPTORS AND FDRC$A AND 
ACCESS SECTION POINTERS — ACCESS MODE FOR BLOCK FDBK$A 


FILE OPEN SECTION ASSOCIATED LUN 1 FDOP$A 


BLOCK BUFFER MULTI—BUFFERING DESCRIPTOR FDBFSA 
SECTION BUFFER SIZE 

POINTERS IN FDOP$A 
FILE NAME FILE SPECIFICATION (BUILT AT OPEN FROM 
BLOCK SECTION FILE ID DSPT OR NAME BLOCK 


PLUS INFO. FROM FILE) 


TK-7740 


Figure 1@-4 The File Descriptor Block 
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Allocating Space for FDBs - Use the FDBDFS macro to allocate space 
for one FDB. The format of the call is: 


label: FDBDFS 


FDBIN: FDBDFS$ 


The label is used later to refer to a specific FDB. 


Initializing an FDB - You can initialize an FDB either at assembly 
time or at run time. Whenever possible, use the assembly-time 
macros because they do not need to be executed at run-time. 
Therefore, your task will be more run-time efficient. With the 
assembly-time macros, use parameters which are valid source 
arguments for .WORD or .BYTE assembler directives. Many values 
have symbolic equivalents which can be used instead of the actual 
numeric values. 


With the run-time macros, use parameters which are valid 
source arguments for MOV or MOVB instructions. This is similar to 
the convention for the $ form versus the $S form of the executive 
directives. At assembly time, use FCS macros which end with SA; 
at run time, use FCS macros which end with $R. The assembly-time 
macros muSt immediately follow the FDBDF$ macro which reserves 
space for the FDB. The run-time macros have an additional initial 
argument to specify which FDB they refer to. 


Run-time initialization macros override any previous’ FDB 
settings. In addition, you can also override the settings in the 
file open operation or in an I/O operation. 


As an aid in referencing a given FDB at run time, all FCS 
run-time initialization and file-processing macros return the FDB 
address in R@. If no FDB pointer is specified in subsequent FCS 
macro calls, it defaults to R@. The other registers are saved and 
restored by all FCS run-time macros. 


For additional information on the use of parameters in the 
different forms of the FCS macro calls, see section 2.2.1 on 
Assembly-Time FDB Initialization Macros, and section 2.2.2.1 on 
Run-Time F DB Macro-Call Exceptions in the IAS/RSX-11 I/0 
Operations Reference Manual. 


The following sections describe how to use the different FCS 
FDB initialization macros to initialize an FDB. 
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Specifying New File Characteristics 


Use either the FDATSA macro, at assembly time, or the FDATSR 
macro, at run time, to specify new file characteristics. These 
macros are only required where you create a new file. FCS uses 
the established characteristics for existing files. The format of 
the FDATSA.macro is: 


FDATSA rtyp,ratt,rsiz,cntg,aloc 


rtyp - record type 
R.FIX = fixed length 


R.VAR = variable length 
R.SEQ = sequenced 
ratt - record attributes 


carriage control 
FD.FTN = FORTRAN type 
FD.CR = list type 
default = no implied carriage control 
spanning of blocks 
FD.BLK = spanning blocks not allowed 
default = spanning blocks is allowed 
rsiz - record size 
cntg - initial number of blocks for file 
aloc - extend size for file. 


Examples: 


1. FDATSA R.VAR 


File will have variable-length records. Defaults: no 
implied carriage control, may span block boundaries, 
initial size of zero blocks, default extend size, on 


disk, generally five blocks. 
va FDATSA R.FIX,FD.CR,64. 


File will have fixed-length records, list carriage 
control, and 64(18) byte records. Defaults: records may 
span block boundaries, initial size of zero blocks 
default extend size. 
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Bs FDATSA R.FIX,RD. FTN! FD.BLK,100. rel Ss 


File to have fixed-length records, FORTRAN type carriage 
control; records may not span block boundaries; 19@(19) 
byte records, initial file size of 15(1@) blocks, not 
necessarily contiguous. Default: default extend size. 


4. FDATSR #FPBD1,#R.FIX,#FD.FTN! FD.BLK, #100.,#15. 


The same as the previous example, but using the run-time 
form. | 


Note the difference in the format of the parameters in the SA 
(for assembly-time) and the $R (for run-time) forms. For the SA 
form, the parameters are symbolic or numeric values, all valid 
source arguments for .WORD or .BYTE assembler directives. For the 
SR form, on the other hand, the parameters are all valid source 
arguments for MOV or MOVB instructions. 


If records are allowed to span block boundaries, then a 
record at the end of a block, which doesn't fit completely within 
the block, is continued in the next block. Tf records are not 
allowed to span block boundaries, a record which doesn't fit 
completely is started at the beginning of the next block. The 
Space remaining in the current block is unused. This technique 
uses more file space, but permits quicker I/O operations in locate 
mode. 


Specify one of three possible types of carriage control in 
the ratt parameter. FD.FTN indicates that the first data byte of 
each record contains a FORTRAN carriage-control character (e.g., 
space for single space, @ for double space). FD.CR indicates that 
when the record is written to a line printer or a terminal, each 
record is to be preceded by an <LF> character and followed by a 
<CR> character. This causes single spacing between records in the 
printout. If you specify neither FD.FTN nor FD.CR, no carriage 
control is implied. Any carriage control characters must be 
imbedded in the data. List (.LST) files are set up with no 
implied carriage control. 


See section 2.2.1.2 on FDATSA in the TAS/RSX-11 I/O 


Operations Reference Manual for additional information on the 
FDATSA parameters. 
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Selecting Data Access Methods 


First decide whether to use block I/0 or _ record I/O. 
Normally use block I/O for files with no record structure, and 
record I/O for record structured files. However, block I/O is 
faster than record I/0, because no blocking or deblocking of 
records is required, and transfers are made directly between the 
device and the user buffer. Therefore, if your operation does not 
require accessing individual records within the file, e.g., a file 
copy operation, use block I/O because it is more efficient. 


After you select block I/O or record I/0, there are some 
other considerations. For block 1/0, no FSR block buffer is 
needed. Instead, you must specify a user buffer. Block I/O is 
asynchronous; set up an event flag or an AST for synchronization. 
Also, you must uSe the additional FDBKSA or FDBKSR macro- to 
specify the user buffer and the synchronization techniques. 


For record I/O, choose either sequential access or random 
access mode. Sequential access can be performed on files with 
either variable-length records Or fixed-length records. 
Successive PUTS or GETS operations in sequential access mode 
access successive records in the file. This is useful if you need 
to process all records in the file in order. [It is required if 
the file has variable-length records. 


Random access can be_- performed only in files with 
fixed-length records. With random access, your program can access 
records randomly by specifying a record number in each PUTS or 
GETS call. Random access is desirable if you want to access 
records in an order which is different from their order in the 
file. 


With sequential access, you can use FCS routine to. save 
pointers to an accessed record, and later return to that record. 
This offers you a limited ability to access records in a_ random 
order, or at least an ability to back up to a certain point in the 
file and continue from there. The actual subroutines are 
discussed later in this module under Performing I/O. 


For record I/O, an FSR block buffer is used for the actual 
I/O transfers, Blocking and deblocking of records is done 
transparently for you by FCS. When FCS blocks a record on output, 
it places it into one -or more virtual blocks as needed. When FCS 
deblocks a record on input, it takes one or more virtual blocks 
and constructs a logical record. Because GETS/PUTS operations, 
used for record I/0, process records which are contained in 
virtual blocks, not all I/O operations cause an actual I/0 
transfer. Generally, an I/O transfer is needed only when the end 
of a block is reached. 
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“You may choose either move mode or locate mode. Figure 19-2 
compares the two. In move mode, you always access records in a 
user specified buffer, sometimes called a user record buffer. 
Move mode is simple to program, but every PUTS or GETS operation 
requires an extra transfer of the record between the user record 
buffer and the FSR block buffer. A user record buffer is 
required. 


In locate mode, aS long as complete records are located 
totally within an FSR block buffer, you access the record directly 
in the FSR block buffer. FCS returns information in the FDB about 
the location and the size of the record. If records are allowed 
to span block boundaries and the last record in a block does’~ span 
the block boundary, then the full record cannot be accessed until 
the next virtual block is read (in the case of a GETS operation), 
or until the current virtual block is written (in the case of a 
PUTS operation). In that special case, the record is accessed in 


a user specified buffer. Therefore, a user record buffer is 
required in locate mode only if one or more records actually span 
block boundaries. Table 19-1 summarizes the situations when a 


user record buffer is needed. 


Record I/O operations are synchronous. All synchronization 
is handled for you by FCS. Control is returned to your program 
only after the requested PUTS or GETS operation is completed. 


Table 18-1 When the User Record Buffer Is Needed 
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Specifying Data Access Methods 


Use the FDRCSA or the FDRCSR macro to specify data 
methods. 


FDRCSA racc,urba,urbs 


racc -— type of access 
methods 
FD.RWM = block mode 
FD.RAN = record mode, random I/O 
default = record mode, sequential I/O 


file truncation 


access 


FD.INS = PUTS in middle of file does not truncate 


file 
default = does truncate file 


move or locate 
FD.PLC = locate mode 
default = move mode 
urba - user record buffer address (Table 1@-1) 
urbs —- user record buffer size (in bytes). 
Examples: 


1. FDRCSA ,BUFF,8@. 


Defaults to record I/0, sequential access in move 
User record buffer at BUFF, 8@. bytes long. 


2. FDRCSA FD. RWM 


Block I/O. buffer is specified in FDBKSA macro 
open, READS, or WRITES macros. 


3. FDRCSR #FDB4,#FD.RAN! FD. PLC, #BUFF,#100. 


Record I/O, random access in locate mode. User 


mode. 


or in 


record 


buffer at BUFF, 108. bytes long. This is a run-time 


macro which initializes the FDB at FDB4. 
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If FD.INS is not specified, a PUTS in the middle of the file 
places the logical end-of-file right after that record, which 
truncates the file. If FD.INS is specified, a PUTS in the middle 
of the file does not change the logical end-of-file. See section 
2.2.1.3 on FDRCSA in the IJIAS/RSX-11 I/O Operations Manual for 
additional information. 


Additional Initialization of the FDB for Record 1/O 
Normally, no further initialization is needed for record I/O. 
However, if you wish to override one or more of the defaults, use 
the FDBFSA or the FDBFSR macro. The defaults are included in the 
list of parameters below. The format of the FDBFSA call is: 
FDBFSA efn,ovbs,mbct,mbfg 


efn - event flag used internally for synchronization | 
(default is 32(1@)) 


ovbs 


override FSR block buffer size (in bytes) (default 
is standard block size for device) 


mbct 


multiple buffer count (default generally 1, or 
Single buffering) 


mbfg - multiple buffering type (only for multiple buffering) 


FD.RAH read ahead operations 

FD.WRB write behind operations 

(default - FD.RAH if file opened for read only, 
FD.WRB if file opened for a write operation) 


Examples: 
1. FDBFSA ,,2 


Use double buffering. Defaults: event flag 32(10), FSR 
block buffer size standard for device (e.g., 512(19) 
bytes for disk). Multiple buffering type - read ahead if 
file is opened for read only, write behind if it is 
opened for a write operation. 


24 FDBFSA 12.,2048. 
Use event flag 12(1@) and an FSR block buffer size of 
2048(18) bytes. This is the standard size for ANSI 


Magtape. It can also be used for disks to cut down on 
the number of I/O transfers. Default: single buffering. 
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In the second example, you must reserve enough space in the 
FSR using the FSRZS$ macro. See section 2.2.1.6 on FDBFSA in the 
IAS/RSX-11 I/O Operations Reference Manual for further informa- 


tion. 


Additional Initialization for Block I/O 


For block I/0, you only specify the access method in the 
FDRCSA or FDRCSR macro. You must use the FDBKSA or FDBKSR macro 
to set up the user buffer and your synchronization methods. The 
format of the FDBKSA macro is as follows. 


FDBKSA bkda,bkds,bkvb,bkef ,bkst ,bkdn 


bkda - user buffer address 

bkds - user buffer size (in bytes) 

bkvb - address of two-word virtual block number 

bkef - event flag for synchronization (default = 
32 (19) ) 

bkst - I/0 status block address (must be specified 
for FCS to return I/O status) 

bkdn - AST service routine address 

NOTE 


Bkvb must be specified after the file is 
opened using the S$R form, or in a READS or 
WRITES call. 


Example: 


FDBKSA MYBUF,1024.,,20.,I10ST 


User buffer at MYBUF, size is 1@24(10) bytes. Use event flag 
20(198), the I/O status block is at IOST. No AST routine. 


Bkvb is the address of a two-word data block containing the 
first virtual block number for a block I/O operation. MThis data 
block is copied into the FDB and then used to locate the starting 
block for the I/O operation. 
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However, the virtual block number in the FDB is always 
initialized to ‘'1l' when a file is opened. Therefore, this 
parameter must be specified after the file is opened if you wish 
to start I/0 operations with a block other than virtual block l. 
Do this uSing either a FDBKSR, a READS, or a WRITES call. 


The parameter should be left null if you use the SA form. It 
is present in the $A form only for compatibility with the $R form. 


Bkst is the address of an I/O status'7 block. Unlike record 
I/O, where FCS sets up its own internal I/O status block, block 
I/O requires that you specify an IOSB in order to get I/O status 
reports. FCS issues QIOS for you. With record I/O, FCS reports 
both directive errors and I/O errors automatically. With block 
I/O, I/0 errors are reported only if you specify an IOSB address 
in a FDRKSA or FDBKSR call. 


Initializing the File-Open Section of the FDB 


You must also initialize the file-open section of the FDB 
before opening a file. It contains information about the file to 
be opened. You must set up data structures so that FCS can build 
a file specification for the file. In addition, you must specify 
the LUN to be assigned to the file and the kind of access’ rights 
you need (read, write, extend or delete). You can do all of this 
with an assembly or run-time macro, or in the actual open macro 
call. 


Setting Up the File Specification in the FDB -- At run time, FCS 
constructs a standard file specification in the filename block in 
the FDB uSing the following, in order: 


1. The dataset descriptor 
2. The default filename block 
3. Other defaults of the task or system 


FCS first uses any information which is set up in the dataset 
descriptor. Any non-null data is translated from ASCII to 
~Radix-5@ format, and stored in the appropriate offsets in the 
filename block. If any pieces of the file specification are not 
specified in the dataset descriptor, FCS next checks the default 
filename block for any of the missing pieces. Any missing pieces 
which are found there are filled in next. 
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If the device or the UFD is still not filled in, normal 
system defaults are used. The device defaults to the current LUN 
assignment of the LUN to be used to access the _ file. The UFD 
defaults to the default UIC of the task, which is typically the 
default UIC of the user who runs the task. If the file name or 
the file type are still not filled in, a file open failure occurs. 


If only a dataset descriptor or a default filename block is 
specified, and not both, the missing structure is skipped. 
Typically, the dataset descriptor is used for building file 
Specifications at run time. Several routines (get command line 
(GCML), command string interpreter (CSI), etc.) are available for 
prompting for input, getting a command line, and then filling in a 
dataset descriptor. Typically, the default filename block is used 
to default any fields not specified in the dataset descriptor, or 
to completely set up a file specification at assembly time. 
ae one or both structures may be set up at assembly time, if 

esired. 


If you want to have FCS perform I/O to a terminal, just build 
a file spec with the device TTnn: or TI:. If the specified 
device is a terminal, FCS just issues QIOS to the terminal. The 
advantage of this technique over. issuing QIOS yourself is that the 
same I/O routines work correctly with file-oriented devices’ and 
terminals. You do not have to rewrite the I/O code to change 
between device types. The system utility PIP uses FCS calls’ for 
all of its I/O operations. 


Setting Up the Dataset Descriptor 


The dataset descriptor is a six-word data area in your 
program containing the sizes and the addresses of the ASCII data 
strings that together make up a file specification. The format of 
the data area and the ASCII strings is: 


label: - WORD ldev ,adrdev 
-WORD lufd,adrufd 
~WORD lnam,adrnam 


adrdev: -ASCII /dev/ 


ldev =,-adrdev 

adrufd: - ASCII /ufd/ 

lufd =.-adrufd 

adrnam -ASCII /full name/ 
lnam =.-adrnam 
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Example for file DB1:[202,1]SAMPLE.MAC: 


DSPT: eWORD LDEV, DEV 
eWORD LUFD, UFD 
-WORD LNAM, NAM 

DEV: -ASCII /DB1:/ 


LDEV =.-DEV 

UFD -ASCII /[282,1]/ 
LUFD =.-UFD | 

NAM: -ASCII/SAMPLE.MAC/ 
LNAM =.-LNAM 


This example sets up the dataset descriptor and all of its 
file specification pieces at assembly time. This can also be done 
at run time. As shown above, FCS builds’ the file spec 
DB1:[{202,1]SAMPLE.MAC. If no default filename block is specified, 
the version number takes the normal system default, the latest 
version for an existing file, and the latest version, plus one, 
for a new file. See section 2.4.1 on the Dataset Descriptor of 
the IAS/RSX-11 I/O Operations Reference Manual for additional 
information. 


Setting Up the Default Filename Block 


The default filename block’ is an area within your program 
containing the various elements of a file specification. Use the 
NMBLKS macro call to both reserve space for this area, and to 
initialize it at assembly time. The format of the NMBLKS call is: 


label: NMBLKS fnam,ftyp,fver,dvnm,unit 
Example for file DB1:SAMPLE.MAC: 


NMBLK$ SAMPLE,MAC,DB,1 


Notice that you divide the file specification into pieces in 
the macro call. Also.note that you cannot specify a UFD in the 
default filename block. It can be specified using a dataset 
descriptor. Otherwise, it is usually taken from the default UIC 
of the task. : 


See section 2.4.2 (on Default Filename Block - NMBLKS Macro 
Call) for additional information on the default filename block. 
It also explains how to manually define or override data in the 
default filename block. 
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Initializing the File-Open Section Prior to Opening the File 


Use the FDOPSA or the FDOPSR macro call. The format of the 
FDOPSA call is as follows. 


FDOPSA lun,dspt,dfnb,facc,actl 

lun - LUN for I/O requests 

dspt - pointer to dataset descriptor 

dfnb - pointer to default name block 

facc -— type of file access (Table 19-2) 

actl - access control 

The type of file access indicates the kind of activity that 
you will perform on the file. Table 19-2 lists these types. Note 
that you do not specify read, write, extend, or delete; but 
instead write, read, append, modify, or update. Each implies a 


request for a particular set of access rights. The meanings of 
the types are: 


Write - Write (create) a new file. 
read - Read an existing file. 
append —- Append (add) data to the end of an existing file. 


modify - Modify an existing file without changing its length. 


update - Update an existing file, extending its length if 
necessary. 


In all cases, the file can also be read. 
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The actl parameter is used to override the defaults for 
certain FDB control information, namely: 


e Initial magnetic tape position - default depends on file 
operation. 


e Locking of a disk file opened for write if it is not 
properly closed, e.g., if the task is aborted. Default is 
that the file is locked. 


e The number of retrieval pointers in pool for a disk file 
window. Default is volume default. 


e Enable or disable block locking. Default is disable block 
locking. 


See section 2.2.1.5 on FDOPSA in the IAS/RSX-11 I/0 
Operation Reference Manual for an explanation of the defaults, and 


the arguments to override’ them. This section also covers 
additional information on the FDOPSA and the FDOPSR macros. 


If desired, you can specify all of the FDOPSA or FDOPSR 
Parameters, except actl, in the open macro call instead. The 
following examples show the use of the FDOPSA call, dataset 
descriptors, and default filename blocks. 
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Examples: 


1. 
FDOPSA 1,,DFNB 


DF NB: NMBLKS MYFILE,DAT,,DB,@ 


Use LUN 1, build the file spec in the FDB with the default 
filename block (since there is no dataset descriptor). MThe 
file spec will be DB@:MYFILE.DAT. The UFD will be taken from 
the default UIC of the task; the version number takes the 
normal default. 


26 
FDOPSA 2,DSPT 


DSPT: -WORD  4@,@ 
-WORD  LUFD,ADRUFD 
-WORD  LNAM,ADRNAM 
ADRUFD: .ASCII /[15,12]/ 


LUFD =.,-ADRUFD 
ADRNAM: .ASCII /MYFILE.FFF;3/ 
LNAM =.-ADRNAM 


Use LUN 2, build the file spec first with the dataset 
descriptor, then go to task and system defaults (since there 
is no default filename block). The File spec will be 
[15,12]MYFILE.FFF;3. The device will be defaulted to the 
current LUN assignment and to SY: if not currently assigned. 


FDOPSA 1,DSPT1,DFNB1,FO.WRT 


DFNB1: NMBLKS ANY,FIL 

DSPT1: eWORD LDEV, DEV 
-WORD 0,0 
-WORD LNAM, NAM 


DEV: ~-ASCII /DK2:/ 
LDEV =.-DEV 
DNAM: ~-ASCII /MINE/ 
LNAM =.-NAM 
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Use LUN 1; open the file for write (create a new file). 
Build the file spec first from the dataset descriptor, then 
fill in any missing information from the default filename 
block. The resulting file spec will be DK2:MINE.FIL. The 
UFD and version number take normal system defaults. The 
filename is MINE because the dataset descriptor is used 
first. Since the name is then filled in, the default 
filename block is not checked for a name. 


Examples of Setting up an FDB 


The following examples show the complete process of setting 
up and initializing FDBs at assembly time before opening a file. 
Two examples are included for creating a new file, plus two for 
accessing an existing file. The line comments offer an 
explanation of the examples. 


Creating a New File: - 


1. 
FSRSZS a : 1 file will be open for 
: ; record I/0 
FDB1: FDBDFS 
FDATSA R.VAR,RD.CR ; Variable length records, 
> "list" carriage control 
FDRCSA’_ ,BUFF,8®. ; URB at BUFF, length 8@. 
; bytes. Defaults: sequential 
:; access, move mode 
FDOPSA 2,,DFNB ; USe LUN 2, file spec from 
; Default Name Block 
DF NB : NMBLKS VARIABLE,ASC ; File Spec VARIABLE.ASC 
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DS PT: 


NAM: 
LNAM 


FSRSZS$ 


FDBDFS$ 
FDATSA 


FDRCSA 


- FDOPSA 


-WORD 
-WORD 
-WORD 
-ASCITI 


=e —-NAM 
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R.FIX,FD.FTN,8@, 


RD. RAN, BUFF ,890. 
1,DSPT,,FO.WRT 
0,0 


Q,@ 
LNAM, NAM 


./MINE.FIL;2/ 


Accessing an Existing File: 


1. 


FDB1: 


FSRSZS$ 


FDBDFS$ 
FDRCSA 


FDOPSA 


,URB,25. 


3,,DFNB 
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me «68 MO MO FO 


Fixed length records, 
FORTRAN carriage control, 
88. byte records - 
Random access, URB at BUFF, 
length is 89. bytes 

Use LUN 1, build file spec 
from dataset descriptor, 
open a new file for write 
Use default device 

Use default UFD 

Pointer to file spec 

File name 

Length of file name 


URB at URB, length = 25. 
bytes. Defaults: sequential 
access, move mode 

Use LUN 3, build file spec 
from Default Name Block 


FDB1: 


FDBI: 


FDBO: 


DSPTO: 


DEV: 
LDEV 


FILE CONTROL SERVICES 


Only block I/O 


FSRSZS$ 4) i 
FDBDFS 
FDRCSA FD.RWM ; Block I/O, no URB needed 
FDBKSA BUFF,512. ; For block I/O - sets up 
; buffer at BUFF, length = 
; 512. bytes 
FDOPSA 2, ,DFNB ; Use LUN 2, build file spec 
a 


The example below shows two FDBs. 


from Default Name Block 


LEARNING ACTIVITY 19-1 


The second 


FDB is filled in to display a file ata 
terminal. Fill in the first FDB for ae file 
YOURS.MAC, with variable length records which 
will be read and displayed. Use sequential 
access in locate mode. 


FSRSZS$ 2 ; 2 "Files" open for record I/0 
; To be filled in by the student 
FDBDFS 
FDATSA R.VAR,RD.CR ; Variable length records, 
; implied carriage return, 
; line feed 
FDRCSA ,BUFF, 8@. ; Sequential I/0, move mode, 
; URB at BUFF, length = 8@. 
; bytes 
FDOPSA 2,DSPTO ; Use LUN 2, override LUN 
; assignment. Build file spec 
; using dataset descriptor 
.»WORD LDEV, DEV ; pointers to ASCII data 
-WORD 0,@ 
«WORD 8, @ 
-ASCII /TI:/ ; Device is TI: 
=.-DEV 
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Opening a File 

Whether or not you set the file access parameter with an 
FDOPSA or FDOPSR macro call, you can use the general OPENS macro 
call to open the file. If the access parameter is not already 
specified, specify it in the OPENS call. you can also use a 
number of other open macro calls, which have ae single letter 
suffix to specify the file access. See Table 19-2 for the 
suffixes and their meanings. With file open macros, you can 
choose: 

e Whether shared access is allowed 


e Whether a file is permanent or temporary (deleted when 
closed) 


e Which FCS object modules are used to open the file. 
The following list shows all of the possible open macros. 
OPENS fdb,facc,lun,dspt,dfnb,racc,urba,urbs,err 

- General form 


- File access specified in facc or previously using 
FDOPSA or FDOPSR 


OPENSx* fdb,lun,dspt,racc,urba,urbs,err 


- used for most applications 
- Requests exclusive write access, shared read access 


OPNSSx fdb,lun,dspt,racc,urba,urbs,err 
- Allows shared access 
OPNTSD £fdb,lun,dspt,racc,urba,urbs,err 
~- Opens temporary file, deletes when closed 
OF IDSx fdb,lun,dspt,racc,urba,urbs,err 
- Opens file by file ID 
OFNBSx fdb,lun,dspt,racc,urba,urbs,err 


-~ Specifies file by file name block. 


* The "x" in the macro name represents one of the suffixes listed 
in Table 19-2. 
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Examples: 

OPENS #FDB1,#FO.WRT,7¢777,ERR1 

Open the file using the FDB at FDBl1 for write access (create 
a new file). Call ERR1 on an error. All other information 
is already in the FDB. 

OPENSW #FDB1l,-+77,7,ERR1 


The same as the last example, only using the other form of 
the call. 


OPNTSD #FDB3, 77777 ERR2 


Open a new file as a temporary file using the FDB at FDB3. 
Call ERR2 on an error. 


OPNSSU RO,#3 77777, ERR5 


Open the file for update using the FDB whose address is in 
R@. Allow shared access. Use LUN 3. Call ERR3 on an error. 


OPENS RO,#FO. UPD! FA.SHR,#3,7,77,7,ERR5 

The same as the last example, using the OPENS form of the 
call. 

OPENS 

Open the file using the FDB pointed to by R@. All 


information is already in the FDB. The user should check the 
carry flag for an error. 


There is no difference in functionality between the OPENS 
macro with the facc argument filled in, and the OPENSx, OPNSSx, or 
OPNTSD forms. Use the form which is most convenient. 


OFNBSx uses information already in the filename block of the 
FDB to open the file. When this occurs, FCS does not build a file 
spec prior to the open call. This is more efficient if the 
filename block is still intact, or has been restored after a 
previous open and close of the file. However, the OFNBSX call 
causes the Task Builder to include different object modules in 
your task, thus increasing your task's size. These will be 
additional modules unless OFNBSx is already used in your program. 
The same run-time savings can be achieved if you first fill in the 
filename block and then use an OPENS, OPENSx, or OPNSSx call, with 
no additional object modules added. 
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OPFNBSx is useful only in overlay situations, or when OFNBSX 
is already included. Note that the Get Command Line routine 
(GCML) uSes OFNBSX. 


As shown in the last module, accessing a _ file-by-file 
specification involves a minimum of six disk reads (see Figure 
9-5). If you know the file ID of a file, opening the file-by-file 
ID reduces the number of file accesses to two. This is possible 
if you reopen a file for a second time or use other FCS routines 
to obtain the file ID. This is because the file ID allows direct 
access to the file header of the file. 


Any time the file ID field in the FDB is filled in, any open 
macro call automatically opens the file-by-file ID. The OFIDSx 
call performs the same function, but like the OFNBSx call, it 
causes the Task Builder to include different object modules in 
your task, thus increasing its size. Therefore, fill in the file 
ID and use the regular open macros to open a file-by-file ID. 
Only use the OFIDS$x call in an overlay situation, or if OFIDSx has 
already been included in your task. 
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ERROR CHECKING 


If an error condition is detected during any of the file 
processing operations, the FCS routines set the carry bit in the 
processor status word (PSW), and return the error code and_ the 
type of error to FDB offset locations F.ERR and F.ERR+1. 


The run-time FDB initialization macros are an exception to 
this convention. They do not return any error indications because 
they involve only moves into FDB locations. The FCS 
file-processing routines issue appropriate QIOs for you. 


As with regular QIOS you isSue yourself, directive errors or 
I/O errors can occur. For record I/O, FCS returns the error codes 
to the offset F.ERR of the FDB for you so that you don't have to 
check the I/O status block and the directive status word (DSW) 
directly yourself. The error codes are always returned as_ byte 
values. Since some of the error code values for directive and I/0 
errors overlap, another byte, offset location F.ERR+1 in the FDB, 
contains an indicator, whether the error was a directive or an I/0 
error. A value of '@' in F.ERR+1 indicates an I/O error, a 
negative value indicates a directive error. 


Therefore, to check for errors, check the carry bit on return 
from each file-processing FCS macro call. If there is an error, 
use a TSTB to check offset location F.ERR+1 to distinguish whether 
it is an I/O error or a directive error. Then, check and display 
the error code value. The following section of code shows a 
technique for doing this. 
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Example of Error Checking and Processing 


BUFF: - BLKB 8B : Output buffer 
ARG: - BLKW 1 > Argument block for SEDMSG 
EDIR: e-ASCIZ /FCS DIRECTIVE ERROR. ERROR CODE = $D./ 
EIO: e-ASCIZ ?FCC I/O ERROR. ERROR CODE = $D.? 

- EVEN 


OPENSW #FDB 
BCS ERR1 


Open file 
; Branch on FCS error 


me 


;Error Processing 


ERR1: TSTB F.ERR+1 (RQ) ; Directive error or I/0 
3; error? 
BEQ IO : Branch on I/O error 
MOV #EDIR,R1 ; Addr of directive error text 
; string for SEDMSG 
BR FINSET ; Branch to common code 
IO: MOV #EIO,R1 ; Addr of I/O error text string 
; for SEDMSG signs 
FNSET: MOVB F.ERR(R@) ,RO ; Sign extend FCS error 
MOV R@,ARG ; code and place 
MOV #ARG,R2 ; in arg block 
MOV #BUFF,R@ ; Output buffer 
CALL SEDMSG ; Edit error message 
QIOWSS #IO.WVB,#5,#1,,,,<#BUFF,R1,#40> ; Display message 
BCS ERRQIO ; Branch on directive error 
EXITSS 3; Exit 
ERRQIO: ‘ 
" ; Directive error code 


Using the READS and WRITES macros, directive errors are 
returned normally by FCS. Unlike record I/O, with block I/O FCS 
does not set up an internal IOSB for you. Therefore, you will not 
get I/0 success or failure indications if you do not set up and 
specify an IOSB. 
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The error code is sign extended because SEDMSG works only on 


word values, not on byte values. The error codes and their 
meanings are listed in Appendix I of the IAS/RSX-11 I/0 
Operations Reference Manual. They are also in the RSX-11M Mini 


Reference. Just the directive error codes are in Appendix B of 
the Executive Reference Manual, and just the I/O error codes are 
in Appendix B of the RSX-11M/M-PLUS I/O Driver's Reference Manual. 


You can also specify the address of your own error-handling 
routine, and specify it as the last macro call parameter. A JSR 
PC instruction to the specified user routine is generated. This 
takes the place of the BCS, and causes a call to the 
error—handling subroutine in the case of an FCS error. Note that 
it is a JSR PC which places the return address on the stack. You 
must clear off the stack for a nonfatal error if you do not use a 
return at the end of the error routine. 
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PERFORMING RECORD I/O 
Different Forms of PUT$ and GET$ 
The three different forms of the PUTS and GETS macros are: 
e GETS and PUTS 
- Used for sequential access 
-- Can also be used for random access if either: 
Records are actually accessed in sequence 


Program manually changes record number field 
the FDB 


e GETSS and puUTSS 

- used for sequential access only 

- Takes less space than GETS and PUTS 

- Used only to optimize space in an overlaid task 
e GETSR and PUTSR 

- Used for random access only. 
The formats of the macro calls are: 


GETS fdb,urba,urbs,err 


GETSS fdb,urba,urbs,err 
GETSR fdb,urba,urbs,lrcnm,hrcenm,err 


urba and urbs override any previous URB setups 


lrcnm and hrcnm - the low word and high word of 
the record number (random I/O only) 


PUTS fdb,nrba,nrbs,err 
PUTSS fdb,nrba,nrbs,err 
PUTSR fdb,nrba,nrbs,lrenm,hrenm,err 


nrba and nrbs override the previous settings 
for the next record buffer (NRB) 
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Examples: 
PUTS #FDB1,,,ERR 


Write the record pointed to by the next record buffer pointer 
into the file at the current location. Use the FDB at FDB1l. 


GETSR ,#MYBUF,#64.,#93. 


Read record 93(1@) into the buffer MYBUF. The buffer length 
is 64(180). R@ contains the FDB address. 


Sequential Access 


For sequential access, use PUTS and GETS, or PUTSS and GETSS. 
FCS uses internal pointers to identify the record to be operated 
on next. The initial pointer location is at the beginning of the 
file unless the file is opened for Append. In that case, the 
original pointer location is at the end of the file. Each PUTS or 
GET$ operation sets the pointers to the record after the record 
just accessed. This means that a series of PUTSS or a _ series of 
GETSs work on successive records. 


To update a record in place, you cannot use a GETS, then 
update the record, and then use a PUTS. With that seqeunce, the 
GETS updates the record after the one you read. Instead, use two 
special file control routines, .MARK and .POINT, which allow you 
to save and reset the internal pointers. Use a .MARK before you 
do the GETS, and save the returned pointers to the record. Then 
do a GETS and update the record. Use a .POINT to reset’ the 
internal pointers. Finally, issue a PUTS to update the record. 
See sections 4.19.1 on .POINT, and 4.19.3 on .MARK, in the 
IAS/RSX-11 I/O Operations Reference Manual for details on how to 
use these routines. 


After all GETS operations, the next record buffer (NRB) 
descriptors identify the address and length of the record just 
read. The address is located at offset F.NRBD+2 in the FDB, and 
the length is at offset F.NRBD. | 


For all PUTS operations, the NRB descriptors identify the 
“record to be written. Depending on whether you use move or locate 
mode, as described in the following paragraphs, you may or may not 
need to use the NRB descriptors. 
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In move mode (Figure 19-2), GETS operations always move the 
record read to the user specified record buffer. Therefore, in 
general, specify the URB address and size once (in a FDRCSA, 
FDRCSR, or a file open call). Once these are set up, do not 
Specify them again unless you want to use a different buffer. 
After each GETS, access the record directly in the URB, which has 
a known address. If you specify a different URB in a GETS call, 
that becomes the URB for later GETS calls, unless another URB is 
specified. 


PUTS operations in move mode (Figure 18-2) assume that the 
record has been built at the location set up in the NRB 
descriptor. This defaults to the  URB. Therefore, the easiest 
method is to specify the URB once, and then build all records in 
the URB. Then issue PUTSs without specifying an NRB. 


If you want to build your records in a different buffer, you 
must specify an NRB in the first PUT$ call. After that, for 
successive PUTSs, build all records in the NRB so that you won't 
have to respecify. an NRB. If however, you mix GETSs and PUTSs, 
you must specify your NRB in each PUTS call, because each GETS 
call updates the NRB descriptors to point to the record just read 
(specifically the NRB pointer points to the URB). 


In locate mode (Figure 19-2), you generally access' records 
directly in the FSR block buffer. The only time a user record is 
needed is if a record spans block boundaries. Set up a URB_ only 
if this is a possibility. 


For GETS operations, the NRB descriptors identify the record 
just read. Access the record at the NRB address’ (offset 
F.NRBD+2). This pointer points directly into the FSR block buffer 
if the record does not span block buffer boundaries. 


For records which span block buffer boundaries, FCS moves the 
record to the URB and the NRB pointer points to the URB instead of 
a location within the FSR block buffer. Do not specify a new  URB 
unless you want to use a different URB for records that span block 
boundaries. 


For PUTS operations in locate mode (Figure 19-2), build the 
record at the NRB address. This assumes that the NRB descriptors 
have already been updated to point to the record to be built, 
either by the file open macro, or the previous PUTS or GETS. Once 
the record is built, use a PUTS to allow FCS to do some _ internal 
bookkeeping and update its internal pointers for the next 
operation. 
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In locate mode, be very careful when you write to ae file, 
because you are working directly in the FSR block buffer. I£ you 
build a record in the wrong location by mistake, you cannot easily 
recover any record which gets overwritten. In move mode, on the 
other hand, since you work in a separate URB buffer, a mistake 
discovered before issuing a PUTS does not update the FSR block 
buffer. 


For both move and locate modes, you can also use the  .POINT 
routine to return to the beginning of a file, or the .MARK and 
-POINT routines to save and later return to a record previously 
accessed. This allows a very limited form of random access. 


Random Access 


For random access, use PUTS and GETS or PUTSR and ~GETSR. 
PUTSR and GETSR are easier to use because you can specify the 
record number in the macro call. For random operations, on _ each 
PUTS or GETS call, the record number field in the FDB (offsets 
F.RCNM, high-order word, and F.RCNM+2, low-order word) is used _ to 
calculate the position of the record to be operated on. 


When the file is opened, the record number is always 
initialized to 'l', even if the file is opened for Append. After 
each PUTS or GETS operation, the record number is set to one more 
than the last record accessed. You can override this default by 
specifying a record number in a PUTSR or GETSR call, or by 
manually placing the record number directly into the FDB before a 
PUTS or GETS call. 


For move mode, the URB and NRB mechanics are exactly the same 
as for sequential access. For locate mode, GETS operations are 


the same as for sequential access. 


PUTS operations are very similar. For PUTS operations in 
locate mode, build the record directly at the NRB address. After 
each PUTS operation, the NRB pointer is updated to point to. the 
record after the record written. MTherefore, if you are updating a 
record other than the next record, use either a dummy GETSR call 
or the .POSRC routine to set the NRB pointer to the record to be 
built. See section 4.18.2 on - POSRC in the IAS/RSX-11 
I/O Operation Reference Manual for details on how to use that 
routine. 
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For all types of access, aS you do PUTSS to ae file, FCS 
transparently extends the file as necessary. 


NOTE 

FCS updates the logical end-of-file 
information in the FDB, but not in the file 
header. Close the file uSing the CLOSES 
macro to write the end-of-file information 
out to the file header. See the next 
section, on closing the file, for additional 
information, — 


See sections 3.9 (on GETS) through 3.14 (on PUTS) in the 
IAS/RSX-11 I/O Operation Reference Manual for additional  infor- 


mation on performing record I/0. 


Closing the File 


Use the CLOSES macro to explicitly close a file, specifying 
the address of the FDB. CLOSES performs appropriate cleanup work 


which involves I/O transfers to the file. 


e Waiting for I/O in progress to complete (multiple buffered 
record I/O only) 


e Performing any needed write of ‘the FSR block buffer 
(record I/O only) 


e Updating the file header (high block, end of file block, 
first free byte). 


Since CLOSES performs I/O transfers to the file, always check 
for errors on return to enSure that the transfers were 
successfully performed. If a CLOSES is not issued before a_ task 
exits, the Executive closes the file. If the file was opened with 
write access (write, modify, append, or update), the Executive 
locks the file unless you specify "no lock of files" in the FDOPSA 
or FDOPSR call. 
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Examples of Record I/0 


This section contains several examples which show how to- use 
the various FCS services discussed previously for record I/O. 
Also, look back at Example 19-1, our introductory example. It 
shows how to create a file with variable-length records using 
sequential I/O. Examples 19-2 and 18-3 show how to create a file 
with fixed-length records using sequential I/O. Example 19-2 uses 
the assembly-time FDB initialization macros, and Example 198-3 uses 
the run-time FDB initialization macros. Examples 19-1 to 19-3 all 
use move mode. Example 1@-4 shows how to read records from an 
existing file using locate mode. Example 19-5 shows how to read 
records from an existing file using random access in move mode. 


Example 19-2 creates the file FIXED.ASC. It takes records 
input at TI: and places them in the file, terminating input and 
closing the file when a “Z is’ typed. The following notes are 
keyed to Example 19-2. 


@ symbol for record size. Allows easy modification of the 
record size. 


@ The user record buffer (URB). Input from TI: is read 
into this buffer and then written to the file using PUTSs. 


@ Output buffer, argument block, and format strings’ for 
generating error messages using SEDMSG. This is for both 


QIO errors and FCS errors. 


Allocate FSR space; one FSR block buffer for record I/O. 
The default size is 512(18) bytes. | 


Assembly-time initialization of FDB. 
Open file for write. All FDB parameters are already set. 


The extra ERR1] argument causes a call to the subroutine 
ERR1 in the case of an open error. 


Fill the URB with blanks before each read to avoid garbage 
from a previous read, because you will be reusing the 
buffer. 


Issue read. Check for directive and I/O errors. Display 
an error message and exit on either type of error using 
common code at SHOERR, except for a “Z. In that case, 
branch to a common exit routine which closes the file and 
exits. 2 
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Use PUTS to write the record to the file. FCS takes’ the 
record at NRB (in this case the same as URB by default), 
writes it to the file and updates its internal pointers 
for the next PUTS. Call the subroutine ERR2 in the case 
of an error. 


Branch back, clear the URB and read the next input. 


After a “~Z, close the file, check for errors and exit. 
Use BCS here instead of an additional CLOSES argument, to 
show that this technique is also possible. The two forms 
are similar. The only difference is that BCS does not 
affect the stack, while the additional argument form uses 
a JSR PC, which pushes the return address onto the stack. 


Error processing, as discussed in the section on _ Error 
Checking. This code always issues an explicit CLOSE so 
that the file is unlocked. No error occurs if a file 
which is not yet opened, is closed. This code does not 
distinguish whether the error was caused by the OPENSR, a 
PUTS, or the CLOSES call. Additional code can be added to 
tell which call caused the error. 
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1 
2 
3 
4 $t 
5 ¢ 
6 $ 
7 ¢ 
3 § from 
9 5; A “sz 
10 3- 
11 
12 
13 
14 
15 
@ 16° Rs1z 
17 ost: 
18 PRINT: 
© i9 = BUFF: 
"200—C«COOBUFF? 


a ARG? 
23 
3 24 EFDQIO’ 
2a EFIQIO: 
| 26 EFCIIR: 
27 EFCSIO’ 


32 FDS 


39 0 FILE? 
@ 41 start: 


43 CLREUF 3 
@ 44 
45 LOOF 


Example 19-2 


TI: 


FILE CONTROL SERVICES 


e TITLE 
+ IDENT 
»ENABL 


*MCALL. 
»>MCALL 
*MCALL 
+MCALL 
»+NLIST 
= 30. 
+ RLKW 
QLrOWS 
+ BLINE 
+ BLAB 


BLEW 


*ASCIZ 
+ASCIZ 
eASCIZ 
*ASCIZ 
+EVEN 
+LIST 


FSRSZ$ 
FOELIF $ 
FIRC$A 


FOATS&A 


FROF SA 
NMBLKS 


OFENSW 


MOV 
MOV 
MOVE 
SOB 


CREF XA 
/O17 
LC $s Enable lower case 


File CREFXA.MAC 


CREFXA orens FIXED.ASC for writes inreuts records 
and euts them seauentially to the file. 
terminates ineut and closes the file. 


EXST$C»QlOWSC sQTOWS eDIRS § Sustem macros 
FSRSZ$»FOUBDF $ » NMBLKS + Sustem FCS 
FOURCSAsFUAT&AsFIOFSA $ macros 

OF ENSWe GETS sPUTSsCLOSES ¢ 

Surrress ASCII 

Record size (bytes) 

2 QIO status block 
TO.WVBsSyl9s999<0QBUFF 90240> 


BEX 


“S> 'S> ‘Re 


RSIZ * User record buffer 

80. y Quteut buffer for 
> error messadces 

1 ’ Argument block for 
s $ETMSG 


/TNIRECTIVE ERROR ON QIO. ERROR CODE = “20.7 
71/0 ERROR ON QIO. ERROR CODE = “70.7? 

/FCS DIRECTIVE ERROR. ERROR CODE = “20.7 
?FCS I/70 ERROR. ERROR CODE = “40.7? 


BEX § Show offsets 

1 1 file for record I/0 
File descrirtor block 

y RUFF es RSTZ User buffer and size, 


default is record I/0 

with seauential asccess 
R«FIX»FO.CResRSIZ § Fixed length recordsys 

imPlied <CRS<LF = 

use LUN 1 

FIXED.ASC 


Se “> “Gr “SP E> 


lyyFILE 
FIXED» ASC 


Sr “er > 


QREN¢’ if oren fails» 
CALL ERR 


#F TBs ey ey XE RRA 


y 
¥ 
#RSIZ»R1 > Size of URE 
#BUFF »yR2 » Addr of URE 
#° 9 (R294 ¢ Rlank fill record 
Risloor y $0 mO Sarhase fill 


Creating a File of Fixed Length Records, 
Initializing FDB at Assembly Time (Sheet 1 of 3) 
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47 QTOWS$C IO.RVBeSeissTOST»s<BUFF yRSIZ>3 Read a 
48 5 line from TI? 
49 RCC NIROK * Branch on Tlirective ok 
50 MOV FEF DQTOsR1 + Set ur for SEDMSG 
Sil MOV #$0SWyR2 3° 
ve BR SHOERR > Branch to show error 
ba y and exit 
34 NIROK? TSTE IOST § Check for I/0 error 
rs) bal be BGT OKIO * Branch if I/0 ok 
36 CMFE ¥#IE.EQF » TOST § Check for EOF 
a7 REQ EXIT § If- EQ» close and exit 
38 MOVE IOST»RO >: I/O status is sign 
39 y extended and rlaced 
690 > in argument block 
61 MOV ROs ARG + for $EIMNSG call 
62 MOV #ARG»R2 + Set ur for $EDMSG call 
63 MOV #EFIQIOsvR1 ; 
54 RR SHOERR > Branch to show error 
63 y and exit 
9 46 OKIO? FUT $ #F0Rs»sERR2 s Write next record 
@O«’ ER CLRBUF + Get next record 
68 ’ 
&9 EXIT? CLOSES #FIB 3 Close file 
| 7 RCS ERR $ Branch on FCS error 
71 EXST$C EX#SUC § Exit with status of I 
72 
73 * Error Frocessing 
74 ERR1? 


73 ERR2 3 
76 ERRS $ TSTE F.-ERR+1 (RO) 


77 
78 BEQ I0 
79 MOV FEF COIR y RL 
80 
81. BR FINSET 
2) B2 LOS. MOV #EFCSTOsR1 
83 
84 FINSET? MOVE FsERRCRO) » RO 
85 MOV RO» ARG 
B4 MOV #ARG»R2 
87 ‘ 
88 SHOERR’ MOV #ORUFF » RO 
BY CALL $EDMSG 
90 MOV RivsFRINT+Q. IOPL+ 
Ot DIRS #P RINT 
92 CLOSES #FIB 
93 EXST$C EX$ERR 
94 *END START 


a 
y 
r 
y 
a 
y 
a 
y 
a 
¥ 
a 
9 
a 
y 
a 
y 
a 
bd 
a 
y 
a 
y 
a 
, 
“ 
y 
a 
, 

2 

a 


S> “Sr “Sr 


irective error or I/0 
error 
BKranch om I/Q error 
Set up for $EIMSGy 
directive error 
BKranmch to finish setur 
Set ure for $ENMSGs I/0 
error 
FCS error code 
is sign extended and 
eleced in arg block 
$E0MSG arsument block. 
Quteut buffer 
Format error messase 
§; Size of messase . 
Frint error message 
Close file 
Exit with status of 2 


Example 19-2 Creating a File of Fixed Length Records, 
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Rum Sessionm3 


ZRUN CREF XA 

T1214 

2a 

S35S333 

44 ; 
Where did sow so? 
5646 66 


a 


SERVICES 


Qume of DBLIC S059 30LIFIXEN.ASC#4 ~ File 
Virtual block 0900001 


000000 0461 O61 061 061 061 040 040 
000020 040 040 040 040 040 040 040 
000040 062 062 040 040 040 040 040 


000060 040 040 040 040 040 040 040 


000100 063 063 040 040 040 040 040 
000120 040 040 040 040 040 040 040 
000140 040 040 040 040 040 040 040 
000160 040 040 040 040 040 040 040 
000200 144 040 171 157 165 040 147 
000220 040 040 040 040 040 040 044 
000240 040 040 040 040 040 040 040 
000260 040 040 040 040 000 000 000 
000300 000 000 000 000 000 000 000 


O40 
040 
040 
040 
0490 
040 
040 
040 
157 
066 
O40 
000 
000 


Tt 


~ Size Sir. 


040 
040 
040 
040 
040 
040 
040 
L27 
O77 
0464 
040 
000 
000 


040 
040 
040 
040 
040 
040 
040 
1590 
040 
066 
040 
000 
000 


040 
040 
040 
040 
040 
064 
040 
145 
040 


040. 


040 
000 
000 


2374691370 


bhutes 


040 
040 
040 
040 
040 
064 
040 
162 
040 
066 
040 
000 
000 


040 
040 
040 
063 
040 
040 
040 
145 
040 
066 
040 
000 
000 


040 
040 
040 
063 
040 
040 
040 
040 
040 
040 
040 
000 
000 


040 
062 
040 
063 
040 
040 
040 
144 
040 
040 
040 
000 
000 
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040 
062 
040 
063 
040 
040 
040 
151 
040 
040 
040 
000 
000 


FILE CONTROL SERVICES 


Example 108-3 performs the same function as Example 19-2, but 
it uses the run-time FDB initialization macros. The following 
notes are keyed to Example 19-3. 


1) Include the run-time (SR) macros. 


2) At assembly time, simply allocate space for the FDB_ and 
initialize the default filename block. 


@ Issue the run-time FDB initialization macros, specifying 
the FDB address in the first call. The first call returns 
the FDB address in R@. The subsequent calls default the 


FDB address to RQ@. 
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orens FIXED.ASC 
and ruts them 
A “Z terminates ineut and closes the 


CREF XR 
/O1/ 


LC ’ Enable lower case 


for writes inreuts records 
seauenmtially to the file. 
file. 


the #R macros at rum time to 


EXST#&C ryQlOWSC oQTOWS es DIR ¢ System macros 
FSRSZ$»F UBIF $»>NMELKS $ System FCS 
FURCHSR»FOATH& Re POOF SR > macros 
OFENSW GETS sFUT$eCLOSES ¢ 
BEX § Surperess ASCIT 
’ Record size (iutes) 
a * QIO status block 
TO.WVB: Sey 999 QBUFF sO» 40> 
RSTZ i User Record Buffer 
80, * Quteut buffer for 
* error messases 
1 § Arsument block for 
§ $ETMNSG 
/QIRECTIVE ERROR ON Q10. ERROR CODE = 20.7 
?T/0 ERROR ON QT0. ERROR CONE = Zh. ? 
/FCS DIRECTIVE ERROR. ERROR CODE = “40.7 
?FCS I70 ERROR. ERROR CODE = “40.7. 
REX + Show offsets 
1 * 1 file for record [7/0 
¥ Allocate srace for FIER 
FIXED» ASc § Tefault Name Blocks 
§ for ‘“FIXEDR.ASC’ 
FOUR #R FIX #tF0.CRes#RSIZ ¢ Fixed lensth 
records:s imelied <CR* 
LF 


User huffer addr and 
Sizer move mode and 
sequential access by 
default 


TITLE 
e INENT 
+ENARL 
5+ 
+ File CREFXR.MAC 
+ 
¥ CREFXR 
s from TI? 
5 
3 
§ This Frosgram uses 
’ initialize the FIR 
3 ~ 
*MCALL. 
«MCCALL 
»MCALL- 
*+MCALL 
+NLIST 
RSTZ = 30. 
IOST?: + BLAW 
FRINT? QIriows 
RUFF + BLKE 
QOBUFF? .BLKE 
ARG? »BLAKW 
EFDQIO: .ASCIZ 
EFIQI(IO? .ASCIZ 
EFCOIR? .ASCIZ 
EFCSIO: .ASCIZ 
+EVEN 
+LIST 
FSRSZ$ 
FOR S FOBIIF $ 
NFILES NMBLKS 
START? FIOAT#R 
FORCHR 
FOFSR 


Example 19-3 


Use LUN Ile Nefault 


Name Block 


C 
9 
3 
y  #BRUFF y EROTZ 3 
3 
3 
7 3 
vis» FOF ILE 3 
3 


Creating a File of Fixed Length Records, 
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48 OFENSW yx eee es ERI ¢* OFEN ~ if oren failsys 
49 + CALL ERRI 

50 CLREUF? MOV ¥#RSIZ»R1 ’ Size of URE 

Si MOV #BUFF sR2 ¢ Addr of URE 

32 LOOF? MOVE #/ » C(R2Q)+ * Blank fill record 

a tf SOR Ri» LOOF § $0 mo sgarhase fill 

34 QIOW$C IO.RVEBsSeytysTOSTssiBRUFF s30.> § Read 2 

oo § line from TI? 

U6 BCC IROK § Kranch on Dlirective ok. 
37 MOV #EFTQTOs RA § Set ur for $E0MSG 

38 MOV #$0SWeR2 

o9 ER SHOERR §' Branch to show error 
60 + and exit 

él NIROK? TSTE IQST § Check for I/0 error 

62 RGT OKTO > Kranch if I/0 oF 

63 CMFR #TE..EOF »IOST ¢ Check for EOF 

64 REQ EXIT > If EQs close amd exit 
45 MOVE IOST vs RO s I/O status is sign 

66 5 extended and rlaced 
&7 > in argument block 

68 MOV RO» ARG > for $E0MSG call 

é9 MOV FARG sy R2 § Set use for $ENMSG call 
70 MOV #EFIQTOsR1 3 

71 RR SHOERR + Branch to show error 
72 § and exit 

73 

74 OKIO; FUT $ #F Bs» cE RR2 s Write next record 

735 RR CLREUF + Get mext record 

76 

77 EXIT? CLOSES #F08 * Close file 

78 RCS ERRS § Branch on FCS error 

79 EXST$C EX#SuC § Exit with status of i 
80 

81 y Error Frocessing 

82 ERF A? 

83 ERR2 3 

84 ERRS 3 TSTB F.ERRE1 (RO) i Directive error or I/0 
85 > error 

84 REQ Io § Branch on I/O error 

87 MOV FEF COIR R1 § Set ur for $E0NMSGy 

88 > directive error 

89 RR FINSET > Branch to finish setur 
90 IO: MOV #EFCSIOsR1 + Set ur for $EDMSGy I70 
91 5 error 

92 FINSET? MOVE F.ERRCRO) » RO + FCS error code 

93 MOV ROvARG > is $idm extended and 
94 MOV #ARGeR2 * laced in ars block 
935 s for $E0MSG 


Example 18-3 Creating a File 
Initializing FDB at Run 


of Fixed Length Records, 
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96 SHOERR? MOV #ORUFF » RO + Qutreut buffer 
97 CALL $EOMSG ; Format error message 
98 MOV RisFRINT#HQ.TIOPL+2 + Size of message 
99 IRS #P RINT y Frint error message 
100 CLOSES #FIIB § Close file 
101 EXST$C EX#ERK § Exit with status of 2 
102 +ENTI START 
Run Session 
2RUN CREFXR 
11111 
2ade 
333333 
44 
Where did you so? 
S546& &6 
oy 
ume of DBISC SOS» 301 FIXEN.ASCEIS - File ID) 2456446990 
Virtual block 0000001 - Size Sit. bytes 
000000 O61 061 061 061 O61 040 040 040 040 040 040 040 040 040 040 
000020 040 040 040 040 040 040 040 040 040 040 040 040 040 040 062 
000040 062 062 040 040 040 040 040 040 040 040 040 040 040 040 040 
000060 040 040 040 040 040 040 040 040 040 040 040 040 063 0463 063 
O0O0100 063 063 040 040 040 040 040 040 040 040 040 040 040 040 040 
QO00120 040 040 040 040 040 040 040 040 040 040 064 064 040 040 040 
000140 06040 040 040 040 040 040 040 040 040 040 040 040 040 040 040 
000160 040 040 040 040 040 040 040 040 127 150 145 162 145 040 144 
000200 144 040 171 157 165 040 147 157 077 040 040 040 040 040 040 
000220 040 040 040 040 040 040 066 066 066 066 040 064 066 040 040 
0002490 040 040 040 040 040 040 040 040 040 040 040 040 040 040 040 
000260 040 040 040 040 000 000 000 000 000 000 000 000 000 000 000 
000300 000 000 000 0060 000 000 000 000 000 000 000 000 000 000 000 
Example 19-3 Creating a File of Fixed Length Records, 
Initializing FDB at Run Time (Sheet 3 of 32) 
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Example 10-4 reads the first five records of the file 
VAR1.ASC (which is created uSing Example 19-1) and displays them 
at TI:. It uses seguential I/O in locate mode. The following 
notes are keyed to Example 10-4. 


4) FDB allocation and initialization. Specify locate mode; 
default is sequential access. No FDATSA or FDATSR macro 
is needed because the file already exists. No user record 
buffer is needed because none of the first five records 
spans block boundaries. None span _ block boundaries 
because the maximum input record for Example 19-1 is 
80(10) bytes. Specify a URB if records can span _ block 
boundaries. 


Set up loop counter to read five records. 


GETS a record. The FDB pointer is returned in RQ@ after 
the OPENSR call. 


4 Write the record at TI:. The pointer to the record is at 
offset F.NRBD+2 in FDB; size is at offset F.NRBD in FDB. 
No '#' is used because we want to use the contents of 
those locations as arguments. 


6 Decrement the counter and loop back until done. When 
done, close the file and exit. 


sTITLE REALL 
IDENT /04/ 


~~ 


* 
et 


3 *ENABL. LC § Enable lower case 
4 3+ =. 
g § File READLC.MAC 
& } 
7 § This task reads the first S records from the file 
8 § VART.ASC and diselays them at the terminal. It uses 
9 § locate mode. 
10 3 
ii »MCALL OPEN¢tR » GETS »QTOWSS » NMBLK& oe FDOR SA 
Lie *MCALL CLOSES sEXITS¢S »FOUBDIF Ss FORCHAyFSRSZS 
13 
14 FSRSZ$) 1 § 1 FSR block buffer 
13 FORE FBO $ 
14 FORC#A FIIEPLC + Locate mode 
@ 17 FOOFRSA ts» TIFNE § LUN Ld» default file 
18 ; i mame block. 
19 TIF NE? NMBLAG VARTy ASC ’ File FIXEDR.ASC 
2O ; 
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QOBUFF ? 
22 ARG? 


+BLINW 
»RLAW 


od EFCOIR: .ASCT2Z 
24 EFCSTIO? .ASCIZ 
2 EVEN 
26 START? OFENGR 


BCS 
MOV 
GET $ 
BCS 
QTOWSsS 
SOB 
CLOSES 
BCS 


LOOP 3 


tl 
ae 


35 EXIT#S 
36 § Error code 
3? ERRC 3 


ERE § 
ERRO ? TSTH 
REQ 
MOV 

BR 

MOV 
MOVE 
MOV 
MOV 
MOV 
CALL 
QTOWSS 


IOERR 3 
FINSET3 


wae CLOSES 


53 EXITS 
54 +END 
Rum Session 


7RUN REATILC 
Liii 


22700 19 
Bee teow Aes de ee Ase 


333 
JAZZ Jazz JAZZ 


Jaze 


80, 

1 

/FCS DIRECTIVE & 
“FOS IT/70 ERROR. 


POR 
ERRO 


£5 9 RO 


ERRR 
EIO WVBR #5 9 tl yo 
R29 LOOF 


ERRC 


FL ERR+EI CRO) 


TOERR 

FEF COIR Rd 
FINSET 
FEF CS TOs RA 
Fe ERR CRO) y RO 
ROL ARG 
FARG »e R2 


AFOBUFF y RO 


$E0DMSG 
FIO WVBR ye ty Edy yy 


FTIR 


START 


Have vou ever seen the sun? 


Example 19-4 


Accessing a File 


in 
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* 
9 
a 
bd 


RROR « 
ERROR COQE = 


“> “> Mer > HS “Sh Md cr Me “ED 


S> “SD Me KG > Mb We Me “Ch Sh Se > “D> “ED Me 


Locate Mode 


“#FORUFF oR Ly #40> 5 


SERVICES 


Error messade huffer 
$ENMSG arsument block 
ERROR COQE = “20.7 
Mule 


read 
error 


Oren Pile for 
Branch on FCS 
Loor counter 
Get record 

Kranch on error 


Tecrement loor counter 
Close file 
Branch orn 
Exit 


error 


llirective error or I/0 


error? 
Rranch om I/0 error 
Seto our for #ELMSG 


Branch to diselay code 
Set our for #E0MSG 
Sigm extend FCS 
code and elace 
argument block. 
Quteut buffer 
Format error messade 
Write 


ep rar 
in 


message 
Close file 
Exit 


(Sheet 2 of 


<FOB+F «.NRBD+2 9 FUB+F NR EDs 40> 
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Example 19-5 uses random access to read records from the file 
FIXED.ASC, which is created using either Example 19-2 or Example 


10-3 e 
record 


It prompts at TI: for a record number and displays’ that 
at TI:. The following notes are keyed to Example 19-5. 


FCSMCS is a macro containing .MCALLsS for most of the FCS 
macros. Using it can avoid having to specify all of the 
FCS macros in .MCALL Statements. Note that GETSR is not 
included in FCSMCS$, so it is specified separately. 


Using the $ form of all QIOS. With the exception of the 
QIO at PRINT, all parameters are set at assembly time. 
Therefore, any of the three forms ($, $C, or $S) can be 
used for the QIOS at ECHO, PROMPT, and WARN. Either the §$ 
or the $S can be used for the QIO setup at PRINT. 


The record number is input in ASCII (up to two digits). 


FDB for file. Use random access I/O. 


Open file for read. Prompt for and read record number. 


On a directive error, use the supplied macro DIRERR_ to 
display an error message and the DSW, and then exit. 


Check for I/O error. If the error was a “Z, branch to 
EXIT to close the file and exit. If any other error 
occurred, use the supplied macro IOERR to display an error 
message and the IOSB, and then exit. 


Set up and call .DD2CT to convert the record number’ from 
ASCII to double-precision binary. During setup, make sure 
that at least one digit was input. If none were input, 
prompt again. Double precision is used only to show how 
to take advantage of the full range of record numbers’ (up 
to 31 bits in two words). 


Move the low-order 16 bits of the record number to R2, and 
use GETSR to read the record. Call the subroutine ERR2 on 
any FCS error. Only the low-order 16 bits are needed, 
because we know the record number is less than or equal to 
99(1@). : 


Display the record and prompt for the next record number. 


Always display 38@(1@) characters, because the file has 
fixed-length records, 


472 


FILE CONTROL SERVICES. 


@ on FcS errors, first check for end-of-file. If it is not, 
branch to common FCS error code at ERR3. If the error is 
read past end-of-file, display a warning meSsage and 
prompt for the next input. Because this’ routine is 
entered with a JSR PC instruction, you must clear’ the 

“return address off the stack before uSing a BR 
instruction. 


Notice that the supplied macros DIRERR and IOERR are. used for 
QIO errors, but not for FCS errors. This is because FCS returns 
error status to the FDB. In fact, DIRERR would work correctly 
because the DSW is returned by the Executive, and FCS moves the 
DSW value into the FDB. IOERR however, does not work correctly 
because FCS sets up its own internal I/O status block, and its 
address is not available to the user task. The supplied macro 
FCSERR is set up to handle both types of FCS errors. 
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WON RUD oR 


FILE 


«TITLE | 
TENT 
» ENABL. 


RANTIOM 
/O47 
LG 
+ ‘ 
File RANDOM.MAC 
RANTOM uses 
contains fixed length rec 
TI? for @ record mumber y 
It exits when @ conmtrol Z 


Assemole 


~ RANDOM 


a 
- 
— 

“a> “> M> SP Sr > “> GP SP > Vo Sd S> Wd 


*MCALL 


1? *MCALL FCSMCS 

20 

2 *MCALL OLTRERR» TOERR 
nae FCSMCS 

ea «NLIST BEX 

24 y LOCAL DATA 

ae RSTZ = 30 

26 ECHO $ QTOWS 

27 FRMFPTS QIOWS 


WARNS 
PRINTS 


QILOWS 
QTOWS 


BUFF $ 
LOST Ss 
AREC? 
REC 3 
OUT? 


+BLKE 
+ BLAKW 2 
*BLAW 1 
BLY 
+ BLAKE 
MES *ASCIT 
StZ1 
+ASCIZ 
*ASCIT 
SIZ3 = 
eASCIZ 
eASCIZ 
+EVEN 


/RECORD 
o~MESI 
/FCS ERROR. 
AEXKFAST ENT 
° ~MES3 

/FCS DIRECTI 
“FCS 


NUME 


MES2$ 
MES33 
EFCIIR 3 
EFCSIO3 


Example 19-5 


(Sheet 1 of 
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I/70 ERROR. 


4 
y 


direct eccess to a filey 


Ords. 


and disrelays it 
drat 


is 


QLOWS sDIRSvEXITH&S sGETER § 


Sr > “A> “> Ker 


a 
y 


> “> “Gr M> E> 


ER? / 


ERROR 
FLEE KKK/ 


OF 


VE 


3) 


ERROR + 
COUE = 


CONTROL SERVICES 


Enable lower case 


FIXED. ASC » 
This task 


which 
rromets at 
at Tr? 


amd task-nuild instructions 3 
=MACRO/LIST LEG Cl» LIFROGMACS/LIBRARY scievi lutea d- 


@LINK/MAP RANDOM sL BSC Ls LIPROGSUBS/L IBRARY 


Sustem macros 

Macro to set most 
system FCS macros 
Surrelied macros 

Get most FCS macros 
Surress ASCIT 


Size 


Recard 


IO.WVBy Sede yee CRUFF » 304 ¥ 40> 

IO.RPRe Sel» slTOSTss*ARECy 2s »sMESIySIZ1 + “$s 
TO.WVBs Sele ys ey MESS STZ3 940% 
IO.WVBySelevs ey OQUT es O% 40> 


User record buffer 

I/O status block 

Record oumber in ASCIT 
Record mumber in binary 
$ENMSG outeut buffer 


CONE = “Alte/ 


CONE = 
Alls’ 


Alle / 


AccesSing a File in Random Mode 


FILE CONTROL SERVICES 


FSRSZé 
FOG 3 FORE $ 
FORCéA FOLRAN» RUFF oe RSTZ 
FOOFGA dss F ILE 
FILE NMBLK& FIXED ASC 
»*ENABL LSE 
START? OFENSGR FFUBy yo 99 es ERR 
LO? NIRS EP RMET 
BCC DIROK 
NIRERR <ERROR ON QTO> 
YIROK? TSTE TosT 
BLT ERRIT 
’ Convert ASCIT 
MOV LOST+H#2 5k4 
BKEQ 104 
MOV FAREC 9 RE 
MOV #EREC 9 RS 
CALL +2 CT 
MOV REC+2 9R2 
GETéR #FUBy ys R2y v9 ERRS 
DIRS #ECHO 
BR 10% 
> ERROR ROUTINES 
ERRIIS CMF #IE. EOF» TOST 
REQ EXIT 
ILOERF: #FIOSTs<ERROR ON 
§ Here for errors on GETS& 
ERR ¢ CMF E HIE. EOF es F ERR CRO 
BNE ERR 
§ Just diselay a warnings for 
LTRS TFWARN 
TST CSFO+ 
RR 104% 


Example 14-5 


> “Cs “Se 


a 
¥ 


Sh “> “Eh Sd “SD 


‘S> “> S> “> Me “Se 


Se we 


record rmumber to double-worded 


“> “ES E> “Eh “S> MS MWe SES “He “E> “Oe “Ce > Sd 


1 file orened for 
record I/0 

File descriretor block 
Random gccessy URE 
addr and size 

Use LUN Ll» default 
name block at FILE 

efault name - 


FIXED. ASC 
Oren file for read 
CALL ERRI an orer 


error 
Fromet for 
number 

Rranch on dir ok 


record 


Check for I/O error 
Rraneh on error 
decimal 
# of characters to 
convert 
If mo charactersy 
Fromet asain 
Address of ASCII 
characters 
Buffer to store 
converted rumber 
Convert ASCIT to 
decimal 
Move low order 16 bits 
Get specified record 
Frint it on TI? 
Fromet for mext input 


5 “ZT? 

3’ If ves» branch to EXIT 
QIO: 

> > Was the error an EOF? 
+ Nov it is another 

> error. branch to ERRL 


‘S> “Sh Se E> 


end of file 


lliselay EOF messade 
Clean off return addr 


from stack 


Fromet for mext ineut 
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oS 
96 
?? 
98 
99 
100 
101 
102 
103 
104 
LOS 
104 
107 
108 
109 
110 


iid 
Q) 112 
113 


Rar 


FILE CONTROL SERVICES 


ERRS 3 

ERR 3 MOVE 
MOV 
MOV 
TSTE 
BEQ . 
MOV 
BR 

IOERR? MOV 

QSFPERR: MOV 
CALL 
MOV 


DIRS 
CLOSES 
EXITS&S 
EXIT? CLOSES 
EXIT&S 
END 


Session: 


2RUN RANTIOM 
RECORTD NUMBER? 1 
es i 

RECORD NUMBER ?PS 
333333 

RECORT NUMBER?PS 


KEP AST END OF FILE ORK 


RECORI NUMBERPS 
Where cdicdd vou so? 


ayy 


4 


Example 190-5 


Fe ERR CRO) RS 
RS» TOST 
#IOSTyR2 
F-ERR+1 (RO) 
TOERR 
FEFCIIRe RL 
NSFERR 
FEFCSTOvR 1 
FOUT » RO 
$E0MSG 


S> S> S> S> GW> KP GP “> Ce GP 


RivyPRINT+Q. TOPL+2 


$F RINT 
FF OVE 


#FFUBYERRS 


START 
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‘S> S> Gr “Se Se 


Extend sigim on error 
code and move into 
arsdument block 

I/O or directive error? 

Kranch om I/0 error 

Lirective error messade 

Branch to diserlay code 

I/O errar messase 

Quteut buffer 

Edit ourut message 

i Length of error 

> mMessece 

Frint error messase 

Close file 

EXIT 

Close file 

Exit 


Accessing a File in Random Mode 
(Sheet 3 of 3) 


FILE CONTROL SERVICES 


PERFORMING BLOCK I/O 


READS and WRITES Calls 
The formats of the READS and WRITES calls are: 


READS fdb,bkda,bkds,bkvb,bkef,bkst,bkdn,err 
WRITES fdb,bkda,bkds,bkvb,bkef,bkst,bkdn,err 


All parameters except fdb and err override any previous’ FDB 
settings. Always use a user specified buffer, which can be 
specified in a FDBKSA, or FDBKSR call, an open call, or in a READS 
or WRITES call. 


The length of the transfer is controlled by the bkds 
parameter. The starting virtual block number in the FDB is 
initially set to 1, unless the file is opened for Append. FCS 
updates the block number after each operation to point to the 
block after the last one accessed. To override the default block 
number, set up a two-word data block for the virtual block number 
and specify the address of the block in a FDBKSR macro call (after 
the file is opened), or in a READS or WRITES macro call. 


The following piece of skeletal code shows how to use _ block 
5, then block 12(18), and finally block 13(1@). 


BLCKNM: .WORD 0,5 ; Starting block number 
OPENSR’ #FDB ; Open file 
BCS ERR1 


READS #FDB,,,#BLCKNM,,,ERR2 ; Read block 5 


MOV #12., BLCKNM+2 ; Update block # 
READS #FDB,,,#BLCKNM,,,ERR3 ; Read virtual 
; block 12(19) 


READS #FDB,,r7777ERR4 3; Read next virtual block 
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FILE CONTROL SERVICES 


Unlike record I/0, for block I/O each READS or WRITES causes 
an I/O transfer between the user buffer and the file. : 


Synchronization and Error Checking 


For block I/0, FCS issues asynchronous QIO directives. You 
must provide synchronization and check for both directive and I/0 
errors. Use an event flag or an AST routine for synchronization. 
Check for errors on return from the READS or WRITES call (after 
the QIO directive is issued). 


Also check for I/O errors after the I/O operation completes. 
To get 1/0 error indications, you must set up and specify an I/0 
Status block. Otherwise, no I/O status conditions are returned, 
and success must be assumed. 


If you use an AST routine for synchronization, check the IOSB 
directly for I/O errors. If you use an event flag _ for 
synchronization, use a WAITS call to wait for the flag to be set, 
rather than a Wait for Single Event Flag (WTSES) directive. With 
WAITS, FCS returns its standard error indications. This means the 
carry bit is clear for success and set for an I/O error. In 
addition, for errors, the I/O error code is returned at offset 
F.ERR in the FDB. If you use the Wait for Single Event Flag 
directive (WTSES) instead, standard FCS error codes are not 
returned. In that case, you must check the IOSB directly 
yourself. 


See sections 3.15 (on READS), 3.16 (on WRITES), and 3.17 4x(on 
WAITS) for additional information about block I/O calls, 
synchronization, and error checking. 


Examples 10-6 and 198-7 show how to use block I/O. Example 
19-6 creates a file BLOCK.ASC using block I/O. Example 19-7 reads 
a virtual block from the file BLOCK.ASC and displays it at TI:. 
The following notes are keyed to Example 19-6. 


@ you still need an FSRSZ$ statement to set up an FCS, but 
no FSR block buffers are needed. 


@ FDB setup. FDATSA and FDOPSA are the same as for record 
1/0. The. only difference here is that a dataset 
descriptor is used instead of a default filename block. 
This is done just to show the use of a dataset descriptor. 
FDRCSA specifies read/write mode (block I/O). FDBKSA 
specifies the address and size of the user buffer, the 
event flag for synchronization, and the IOSB_ address. 
Don't specify the address of the block number until after 
opening the file. 
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eo e000 9 


6 0 


FILE CONTROL SERVICES 


Other data structures: A two-word block for the virtual 
block number, initially set to virtual block 1; the user 
buffer, and the I/O status block. | 


Prompt for and read virtual block number. "Low only" 
means only a one-word virtual block number, rather than a 
two-word value. 


Place a terminating null character at the end of the ASCII 
virtual block number to set up for a call to SCDTB. Use 
SCDTB to convert ASCII decimal to binary. There is no 
error check included, but it can be added. 


Move the converted virtual block number to the virtual 
block number block. 


Prompt for and get a character to place in the block. 
Fill the user buffer with the character. 
Open (create) the file. 


Start the I/O transfer. Specify the address of the 
virtual block now, since the "open" call initializes the 
block number to l. 


Display the message and wait for the I/O transfer to 
complete. Using WAITS, FCS returns its standard error 
indications. Call subroutine ERR3 in the case of an 
error. . 


Close the file. 


Set up to display the number of characters’ transferred, 
branch to common code to edit and display the message, and 
then exit. The code is common to the error message code. 


Common error code. Set up for an I/O or directive error 
message. Set up to exit with error status. 


Common code for displaying a message, closing the file, 
and exiting. In the case of a successful write, you end 
up calling CLOSES twice. There is no error for closing 
the file after it is already closed. Use of the common 
code saves space in the task. 
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1 *TITLE BLOCK 

2 *IQENT /01/7 

3 *ENABL LC + Enable lower case 

3+ 

ra > File BLOCK1.MAC 

& ; 

? * BLOCKI creates a file BLOCK.ASC and fills the srecified 
8 i Virtual block of the file with the srecified character. 
9 s It uses block I/0Q0. 

10 37 

11 *MCALL QIOWSs DIRS esQIOWSS*°EXSTSS §¢ Sustem macros 
12 «MCALL FOBDFSsFIURCSAsFORBKSAsFDOPSAsNMBLKS 

13 *«MCALL FDATSAsFSRSZ$*OFENSWY WRITES sWAITSs CLOSES 
14 

1S *«NLIST BEX 

16 MES 3 *ASCII /VIRTUAL BLOCK NUMBER (LOW ONLY)? 7 

17 LEN I = , ~ MES 

18 MES23 *ASCII /CHARACTER: / 

19 LEN2= + ~ MES2 
20 MES33 *ASCII /1 BLOCK BEING WRITTEN TO FILE/ 

a | LENS = , ~ MESS 

22 MES43 *ASCII /WRITE COMPLETED» “0 BYTES WRITTEN TO 7 
a *ASCIZ /FILES 

24 MEST *ASCIZ /FCS DIRECTIVE ERROR: CODE = “40.7 
29 MEST? *-ASCIZ “FCS I/0 ERROR: CODE = Zn. ’ 

26 

27 CHAR 3 + BLRE 1 + Character to write 

28 RUFF? -+BLAB 100, § Buffer for $E0MSG 

2? +LIStT BEX 

30 +EVEN 
31 FSRSZ$ 0 § No FSR block buffers 
32 y needed for block I/0 
33 FOES FOUBOF $ + Reserve FOB srace 

34 FOAT#SA R.-VARsFIRR.FTN + File cheracteristics 
35 FIRCSA F.RWM § Read/write mode 

36 FOEK$A BLOCKsS12.9912TOSB § Adry size of huffery 
37 3 ef i» IOSB addr 

38 FOOPSA 1*0SFT 5 LUN dy SFT 

39 LSE T 3 WORT 0+0 i Lensth and addr of device 
40 +WORT 0+0 i Length and addr of UIC 
41 »WORTD LNAM »NAM ? Lensth and addr of name 
42 NAM3 *ASCIIT /BLOCK.ASC/Z § File name and tyre 

43 LNAM =, -NAM 

44 +EVEN 

45 VEN? +WORT Ovi 3 Default VEN 

4S BLOCKS .BLKW 256- ys User buffer 

47 IOSB? + BLAKW 2 ¢ I/O status block 

48 

49 TYFEL? QIOWS IO.RP Re Selly esTOSKs sc BUFF yds esMESL»LENIT » ’$> 
50 TYFE2?3 QIOWS IO-RPReSelssyecCHARy 1s »MES2eLEN2y» % > 

wd TYFES3 QIOQWS LO.WVRsSe29 99 ecMESSyLENS » 40> 


Example 19-6 
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FILE CONTROL SERVICES 


a § Code 
4 ) 33 START? DIRS #ETYPEL > Fromet and set VEN 
4 MOV IOSEB+2sR0 §y Length im RO 
rs) oO CLARE BUFF CRO) > Fut mull bute at end 
36 MOV #EUFF 9 RO ¢ RO => ASCII distits 
ar CALL $COTER § Convert to binary 
© 38 MOV Ris VEN+2 * Store as low VEN 
O5° WIR$  #TYPE2 3 Input character 
40 ’ Fill user buffer with cheracter 
&1 MOV #BLOCK RO § Get address 
8) &2 MOY #3512.9R1 + and size of user huffer 
63 10%? MOVE CHARs (ROD+ $ Move character 
64 SOB Rivsi10% ’ Loor back until done 
65 $ Oren file to receive characterssy write virtual block 
6 4&6 OPENSW FD Byyyxyy2sERRI §¢ Orens ERRI if mo sood 
©.7 WRITES syv#VENy yy 9ERROS § Start transfer 
o| 68 QNIkS #TYPES +’ Sey transfer started 
&? WATTS ye 9 ERRS s Wait until it’s done 
(12) 79 CLOSES v»vERR4 § Close file 
71 MOV #MES4*Ri 5 Adr of comrletion 
© 72 $ message 
73 MOV #EX$SUCeRS § Exit status 
74 BR FORMAT 3+ Branch to common code 
73 > for messade disrlay 
76 > and exit 
77 ERR? 
78 ERR2? 
7? ERRS$ 
80 ERR4 3 ‘TSTE F.ERR+1 (RO) ¢s [lirective or I/0 error? 
81 BEQ IOERR > Branch om I/O error 
14) 82 MOV #MESItyR1L § => I/O error message 
83 BR FCSSET > Branch to common code 
84 TQOERR? MOV EMEST y Ri 3; => Tlir error message 
B85 FCSSET? MOVE F,ERR CRO) »R4 > Sign extend error code 
86 MOV R49TOSB+2 ys Use I/0 status block 
87 * for ars block 
88 MOV #EX#ERRe RS s Exit status to RS 
89 5 Frint messeser exit with status in RS 
90 FORMAT? 
91 MOV #IOSK+2*R2 y R2 => I/O status 
92 MOV #RUFF » RO s RO => $EDMSG buffer 
93 CALL $E0IMSG > Format the text 
@® 94 QIOWSS #1O.WVB #594299 92 BUFF eR1 #4055 Arid 
93 y write it out to TI? 
96 CLOSES #FIDB » Close file and 
97 EXST#$S RS § Exit with status 
9B +ENT START . 


Example 18-6 Creating a File With Block I/O (Sheet 2 of 3) 


481 


7% 


Fars 


Seca ian 


RUN BLOCK 
BLOCK NUMBER CLOW ONLY): 2 
CHARACTER?) @ 


VIRTUAL. 


eels 


WRITE COMPLETED » 


Yume of 


Tumse of 


000000 
000020 


000040 


000740 


000760 


KK EOF 


BEING 


DR2¢0 30S» S01LIBLOCK.-ASC#10 ~ 


Contains whatever 


QRAIC SOS» SOL IBLOCK ASC#10 


145 


145 


1435 


Example 19-6 


Virtual block OsO0000L ~ 


Virtual 


Creating a File With Block 


FILE CONTROL SERVICES 


WRITTEN TO FILE 
wie BYTES 


WRITTEN TO FILE 


File It 


Sive S12. 


wes Freviously in that 


~ File ru 


block O»000002 ~ SGise Sie. 


145 245 145 145 145 145 145 


145 145 145 145 


3 LAS 14s 


145 145 145 


145 145 145 145 145 
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S7 35592 


373559290 


bytes 


block on 


¥0 


the disk 


bytes 


14S 


145 1 


145 


145 145 
145 


42 


145 145 145 


145 14% 
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FILE CONTROL SERVICES 


Example 19-7 prompts at TI: for a virtual block number, and 


then 


reads and displays that block of BLOCK.ASC. The following 


notes are keyed to the example. 


600 0 


This example displays, in addition to the error codes, 
text error messages which tell the user which FCS call 
caused the error. 


No FSR block buffers are needed for block I/0. 
This is the FDB setup. Use read/write mode, Use FDBKSA 
to specify the user buffer address and size, the event 


flag, and the IOSB address. 


Open the file for read and prompt for the virtual block 
number. 


Place a null byte at the end of block number for a call to 
SCDTB. Use SCDTB to convert the block number from ASCII 
decimal to binary. 


Store the result, returned in Rl by SCDTB, in the low byte 
of the virtual block number block. 


Issue a READS to read the specified block, and use WAITS 
to wait for the I/O operation to complete. READS and 
WAITS return standard FCS status and error returns. 
Display a heading and the virtual block. 


Close the file and exit. 


Error code to display the text message, including’ the 
error code for each type of error. 
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be i pt 
Wwe OSG GN Cd Gi hoe 


hee 


14 


+ 


a> “> “> > “> SP 


CR 

L.F 
MESS 
LENT 
MES 22 $ 
LENZ 
MES3I¢ 
MES SIs 
MES4T¢ 
MES40% 
MESSI 
MESSI 
MESGI$ 
MESSI 
BUFF ¢ 


FOIE? 


FILES 
VENI 
BLOCK? 
LOSE: 
FROMFT % 
DIONE! 
LUMP 


FILE 


*TITLE 
¢« IDENT 


eENABL 


eMCALL 
*MCALL 
«MCALL 


»NLIST 
= 15 
= 12 
“ASCII 


“ASCII 


CONTROL SERVICES 


BLOCKS 
/O1/ 
LC y’ Enable lower case 


File BLOCK2.MAC 


BLOCK? eromets at TI? for ae virtual block number 
and then reads and disrlays that block of "BLOCK.ASC" 


QLOWS ys DIRGsQLOWSS vEXSTS$SVEXITSHS 
FBO $s FURCSA» FORK SA »F DOP SA yNMBLKS 
FSRSZ$» OF ENSRy READS ys WATTS »s CLOSES 


REX 


/VIRTUAL BLOCK NUMBER? 7 


+ ~ MESIL 


“CRSLFS/HERE IS THE BLOCK ¢ /2CRS<LF> 


=. ~ MES2 


»ASCIZ 
«ASCIZ 
+ASCIZ 
*ASCIZ 
»ASCTIZ 
»ASCTIZ 
+ASCIZ 
+ASCIZ 
+ BLAKE 

*LIst 

+EVEN 

FSRSZS 
FOBIIF & 
FIURCEA 
FOERK $A 


FOOF SA 
NMBLKS 


+WORT 
+BLAW 
*BLAW 
QIOWS 
QTOWS 


QTOWSs 


‘T/0 ERROR ON OFENSRsy CODE = “2D. ’ 
/UIRECTIVE ERROR ON OPENSRe CODE = “40.7 
‘T/0 ERROR ON READS» CONE = ZY.’ 
/QIRECTIVE ERROR ON READS» CONE ~ “20.7 
‘T/0 ERROR AFTER WAITS» CODE = “0.” 
/UIRECTIVE ERROR AFTER WAITS» CODE = “4./ 
‘T/0 ERROR ON CLOSE$s CODE = “0, ’ 
/UQIRECTIVE ERROR ON CLOSES» CODE = “40.7 


80. * $ETIMSG outeut buffer 
REX 
0 § No FSR block buffer 
5 meeded for block I/0 
’ FOR for inreut file 
Flt. RWM § Read/write mode 


BLOCK sSi2.92s1sI0SE § Buffer adry size, 
> ef lv iosb adr 

LesFILE § LUN dl» DFNEB 

3 


BLOCK» ASC Name is BLOCK.ASC 
Ovl > Tefault VEN 

256+ § User buffer 

2 ¢’ ITOSE 


IO.RFPRySevlve»TOSBys<BRUPF se dé» esMESLsLENIT » “$> 
> Fromet and get VB # 
TO.WVRe Seles vy tMES2yLEN2@ 40> § Tone 


9 message 
TO.WVBs Selly ve etO964.740> § DTisrelay of VE 


18-7 Reading a File With Block I/O (Sheet 1 of 3) 
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FILE CONTROL SERVICES 


a § Code 
g2 START? 
4 33 OFENSR #FDByssyeseERRL + Orpen file 
34 DIRS $F ROMP T ¢ Ask for a VEN 
oo MOV IOSB+t2 RO § Fut mull at end 
o| 36 CLARE RUFF CRO) ys of disit strings 
37 MOV #EUFF » RO § RO => VEN 
38 CALL $CUiTE § Convert to binary 
QO MOV Red» VENE2 ; Store as low VEN 
@ | 40 REALS #F 0D Ry yy #tVBNy ye vERRO § Read im the block 
él WAIT % yx 9ERRS * Wait until done 
&2 IRS #00NE § Tell them I/0 is done 
63 > Now cdume 8 lines of 64. characters each 
64 MOV #BLOCKsRO § RO => Ist line to dum 
ra] 65 MOV #8.9R1 > €£ of lines to dumr 
66 13 MOV ROvsTUMFP+Q.,IOFL ¢ Addr of current line 
67 IRS #0UMF § Thme it 
48 Anni #4564.9RKO i Foint at next line 
69 SOK Rivis > Tums a@11 8. lines 
o| 7Q CLOSE&  #FDTByERR4 + Close file 
7i EXIT#S 3 Exit 
72 ¢s Error code 
73 ERR? 
74 TSTE F.ERR+1 CRO} 3 I/0 or directive error? 
73 REQ IOERRI i Branch on I/0 error 
7& MOV ¥MES30eR1 3 => Tir error message 3 
77 KR FCSERR + Branch to common code 
78 IOERRI? MOV $MES3I Ri ; => I/O error messade 3 
79 BRR FCSERR > Branch to common code 
86 ERR2 3 
81 TSTE F.-ERR+1 (R03 y I/O or directive error? 
B82 BEQ IOERR2 § KRranch on I/0 error 
83 MOV #€MES409R1 > => Tir error messese 4 
84 BR FCSERR >’ Branch to common code 
85 IQOERR2: MOV #MES4I°R1i »y => [/0 error message 4 
© 86 BR FCSERR > Branch to common code 
37 ERRS? 
83 TSTB F.-ERR+1 (RO) s I/0 or directive error? 
89 REQ IQERRS § Branch om I/0 error 
90 MOV $#MESSIty RA 3 => Dir error messasde 3 
91 - BR FCSERR § Branch to common code 
92 IOERR3? MOV #MESSI»RI1 y => J/0 error message 5 
93 RR FCSERR > Branch to common code 
94 ERR 43 
9S TST F.,ERR+1 (RO> + 1/0 or directive error? 
96 BEQ IOERR4 + Branch on I/0 error 
97 MOV #MESSD 9 RIL 3 => Dir error message 6 
98 BR FCSERR Branch to common code 
99 IQERR4? MOV #MES6I+R1 3 => I/O error messase dé» 
100 > fall into common code 


Example 1@-7 


Reading a File With Block I/O (Sheet 2 of 3) 
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101 FCSERR $ 


102 MOVE F-ERRCRO) 9 R2 § Sign extend error code 
103 MOV R29 TOSK > and move into IOSB 
104 MOV FEX$ERRy RS g Exit status in RS 
103 FORMAT? 
106 MOV #TOSE»R2 + Set ur for $EDMSG 
@ | 107 MOV #EUFF 9 RO ; 
108 CALL $EDMSG 3 
109 QTOWSS #TO.WVB es #5 bis ee sBUFF oR 1 #402 6 § Disrelay 
110 + MeSsSade 
114 CLOSES  ##FIR + Close the file 
112 EXST#S RS ¢ Exit with status 


113 *ENT START 


Kur Session 


“RUN BLOCK? 
VIRTUAL BLOCK? 2 


HERE TS THE BLOCK? 
FEE CREF EOEECEEGEREeEeCAGeceeeEeeeeeeeeceeeseeeeereeeeeeeeeeeeeeee 


| PBFECEGEROCECECEGOCECHLEEEEEEEOCELEELEECHCECELEEEEEEEOEGECEEEEREEEEE 
VSEECECECCEOLECHROECCESCCRHOSCCOESCEHECEEOESECOECECLHOSSCEEECEOECEOCEEEEEECEECGHEECEECEE 


PEG FAGSECCHEEELEeEeECeCEeEECEGeeEReEseeeeeeeeeeeeeeeeeeeeeeeeeeeee 
PECOCLLEEEEEEECECEEEFeEEEEECEEEeEEEEEeEeEeoCEeEesgeeeeeeeeeeeeeeeceeeee 
LEGO PCCECRAESEECECELELOLEEEEEEEEEEEO AEE BEEEREEReEeEEBEEEOEEEFEEAGE 
EVEOEOESE A LOCHEOHOSEEREEEEELEELEEEEEOEEREEEEEEEESeEEEEEEEEOHeEeEeEEeE 


LO PAPCEHECOSEECECEECEEECEBECHMEECOECEGEEEEEEOEFEREEEEeEEEEEEeEEeEReeeE 


Example 1@-7 Reading a File With Block I/O (Sheet 3 of 3) 
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FILE CONTROL SERVICES 


ADDITIONAL TOPICS 


Deleting a File 


Use the DELETS macro to delete a file. If the file is open, 
DELETS closes the file and then deletes it. If the file is 
closed, DELETS just deletes the file. The format of the DELETS 
call is: 


DELETS fdb,err 


DELETS FDB3 


NOTE 
Unlike the DCL DELETE command, if no version 
is specified, the latest version of the file 


is deleted. 


File Control Routines 


You can use a number of internal FCS routines in your’ task. 
Some of the available functions include: 


@e Filling in an FDB filename block from a dataset descriptor 
or default filename block, 


e Finding, inserting, or deleting a directory entry. 
e Marking a place in a file for later return. 


e Setting a pointer to a byte within a virtual block, or to 
the start of a record ina file. 


@e Renaming, extending or truncating a file. 


e Marking a temporary file for deletion, or deleting a file 
by FDB filename block. 


We have already discussed the use of the routines .MARK and 
~-POINT for marking a place in a file so that you can later return 
to it, and .POSRC for locating a record with random access’ in 

locate mode. See Chapter 4 of the IAS/RSX-11 I/O Operations 
Reference Manual for a description of each of the file control 
routines, plus information on how to uSe them. 
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FILE CONTROL SERVICES 


Command Line Processing 


You can use two.other collections of routines to facilitate 
input and processing of command lines, which are useful in general 
or utility tasks. The routines and their functions are: 


e Get Command Line (GCML) 


- Performs command line input operations (issues 
prompts, gets input) 


e Command String Interpreter (CSI) 


- Parses the file specification in a command line from 
GCML into a dataset descriptor, for use by FCS 


- Parses and processes any switches and switch values in 
the command line. 


See Chapter 6 on Command Line Processing in the 
IAS/RSX-11 Operations Reference Manual for a description of the 
command line processing routines. The program CSI.MAC should be 
available on-line (under UFD [20@2,1]). It is also listed in 
Appendix G, and contains an example of the use of GCML and CSI. 
This example is needed to do optional exercise 6 for this module. 


Now do the TestsS/Exercises for this module in the Tests and 
Exercises book. They are all lab problems. Check your answers 
against the solutions provided, either the on-line files (should 
be under UFD [2@2,2]) or the printed copies in the Tests/Exercises 
book. 


If you think that you have mastered the material, ask your 
course administrator to record your’ progress on your Personal 
Progress Plotter. You will then be finished with this course. 


If you think that you have not yet mastered the material, 
return to this module for further study. 
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APPENDICES 


APPENDIX A 
SUPPLIED MACROS 


The supplied macros are designed for simple invocation. They 
are intended for use early in the course (before QIOs are taught) 
to provide easy ways of doing I/O to TI:, and in labs to make 
writing programs easier for the student. They are also used in 
some example programs to allow brevity of code and to establish 
consistency in error checking. 


These macros are contained in the macro library PROGMACS.MLB 
and can be assembled by using the following assembler and 
task-builder calls: 


MACRO/LIST LB: [1,1]PROGMACS/LIBRARY, dev: [ufd] SAMPLE 
(in MCR, MAC SAMPLE, SAMPLE=LB: [1,1]PROGMACS/ML,dev: [ufd] SAMPLE) 


! Needed to include 
! the internal 

! subroutines 

(in MCR, TKB SAMPLE,SAMPLE=SAMPLE,LB:[1,1]PROGSUBS/LB) 


LINK/MAP SAMPLE,LB:[1,1]PROGSUBS/LIBRARY 


NOTE 
If you make copies of PROGMACS.MLB and 
PROGSUBS.OLB in your UFD (or enter a 
synonym), then the LB:[1,1] and the dev: [(ufd] 
can be omitted. 


This appendix includes directions for using the supplied 


macros, the MACRO-1l1l Source code for the macros, and any 
internally-called subroutines. 
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SIMPLE MESSAGE OUTPUT 


Invocations: 


Description: 


Examples: 


Outputs: 


Note: 


Task-Building: 


TYPE <message> 
TYPE <message>,,psect 
TYPE message-address,message-length 


In the first two forms, supply the text of 
the message; the macro will generate the 
storage. Use the second form if you are pro- 
gramming in a Psect other than the default; 
supply the name of the Psect in which you are 
writing. 


In the third form, provide the message address 
and length using standard addressing modes. 
The message can be ASCII or ASCIZ. If it is 
ASCIZ, supply a value of @ for the message 
length; if it is ASCII, supply the length in 
bytes. 


MSGI: -ASCIZ /THIS IS MESSAGE #1/ 
MSG2: -ASCII /THIS IS MESSAGE #2/ 
MSG2LN=.-MSG2 


TYPE #MSG1,4#0 
TYPE #MSG2, #MSG2LN 
TYPE <THIS IS MESSAGE #3> 


All registers are preserved. 


C-bit is set for error; 
clear for no error. 


Event flag 24(18) is used for synchronization. 
Avoid using this flag for other purposes in 
your task. 


This macro requires subroutine modules TYPOUT 
and LENGTH from PROGSUBS.OLB. 
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SIMPLE MESSAGE INPUT 


Invocations: INPUT buffer,length 


Description: Accepts input data from TI:, into specified 
buffer. Length is in bytes. Use standard 
addressing modes for all arguments. 


Outputs: R# points to the input buffer. 
Rl contains the byte count from the I/O status 
block if there is no error. 


C-bit is set for error; 
clear for no error. 


For directive errors, Rl is clear; SDSW 
contains directive error code. 


For I/O errors, Rl contains error code 
from the I/O status block. 


Note: Event flag 24(18@) is used for synchron- 
ization. Avoid using this flag for other 
purposes in your task. 


Task-Building: This macro requires subroutine module TYPIN 
. £rom PROGSUBS.OLB. 
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ERROR MESSAGE MACROS 


Error message macros generate error messageS appropriate to 
Executive directives, I/0 operations, and FCS calls. 


All macros have message, length, and Psect arguments whose 
interpretations are identical to those for the TYPE macro. 
These are used to specify the user-defined section of the 
error message. 


The calling program must check for acceptable errors 


before calling the error message macro, because the error 


routine aborts the task. 


All macros exit unconditionally with "severe error" status 
after the error message is printed. 


All macros require the subroutine modules EREXIT, MTYPOUT, 
and LENGTH from PROGSUBS.OLB. 


EXECUTIVE DIRECTIVE ERRORS 


Invocations: DIRERR <message> 

DIRERR <message>, ,psect 

DIRERR message-address,message-length 
Notes: User should check C-bit and dismiss acceptable 


errors before calling DIRERR. 


Format of DIRECTIVE ERROR 
Message: <user-defined message> 


DSW = <value>. 
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1/O ERRORS 


Invocations: 


Notes: 


Format of 
Message: 


FCS ERRORS 


Invocations: 


Notes: 


Format of 
Message: 


IOERR iosb,<message> 
IOERR iosb,<message>,,psect 
IOERR iosb,message-address,message-length 


iosb is a pointer to the I/O status block. 


User should check the low-order byte of the 
first word of the I/O status block, and dismiss 
acceptable errors before calling IOERR. 


I/O ERROR 
<user-defined message> 
I/O STATUS BLOCK = <hb>,<lb>/<2nd word> 


hb is the high byte of the first word. 
lb is the low byte of the first word. 


FCSERR fdb,<message> 
FCSERR fdb,<message>,,psect 
FCSERR fdb,message-address,message-length 


fbd is a pointer to the file descriptor block 
for the operation which caused the error. 


User should check the C-bit and/or check F.ERR 
in the FDB, and dismiss acceptable errors before 
calling FCSERR. 


“FCS ERROR 


<user-defined message> 
DSW = <value> 


or 
FCS ERROR 


<user-defined message> 
I/O ERROR CODE = <value>. 
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MACRO- 11 CODE FOR SUPPLIED MACROS 


1 «MACRO TYFE MESSGsLENysFSCT 
2 «NL IST 
3 ++ 
4 ¢$ COPYRIGHT (C) 1981 BY DIGITAL EQUIPMENT CORPORATION 
3 3 
6 3 Macro to invoke the "“TYFOUT" routine to tyre a line on 
7 > TIt. 
8 ; 
9 § Invoke usins one of two forms? 
10 ; 
ii ; TYPE “Message. 
12 , or 
13 , TYPE addressylensth 
14 3 
13S > In the first form you srecify the text of the message. 
164 *> The macro reserves storase for the string. 
se 3 
18 § WARNING? The character is used as the delimiter in a 
a9 § -ASCITI directive when vou invoke the first forms so 
20 ; vOU mas mot use this cheracter in your message. 
21 ; 
22 ¢ Im the second form vou must use addressing modes to 
ee + srecifu the address and length of a strings which you 
24 + have reserved in your rrogram. The first arsdument is 
ao § the address of am ASCII or ASCIZ string. The second 
26 * argument should have a value of O if the string is 
27 ¢ ASCIZs else should be the length of the ASCII string. 
2g § addressing modes usinst the stack rointer are not 
29 > sllowed. 
30 3 
31 > If you use the first form and are erogramming in other 
Re > than the blank FPsects you must exrlicitly rrovide 2 
33 y mull "LEN" arguments and srecify a third argument 
34 + (Fesect). This argument must be the name of the FPsect 
35 , im which vou are Frodrammingd. 
34 ; 
37 § Needed subroutine modules? TYFPOUT and LENGTH 
38 j 
39 > sumbols SAYV.Rn = = aif Rn is mot saved on the 
40 5 stack 
4i ; s= QO indicates Rn is stored on 
A? 3 the stack at SAV.Rn(SF). 
43 j~ 
44 +L IST 
43 +GLOBL TYFOUT § Subroutine to issue QIO 
46 5 directive 
47 SAV.RO = ~1 y ASSuMe mo need to save 
48 5 KO 
49 SAV.RL = -1 ¥ ASSUME moa need to save 
50 ; Ri 
ol SAV.R2 = -1 s ASSuMe mo need to save 
a2 § R22 
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«IF & LEN 3 
9 
*FSECT MSGTXT 3 
$$$MES=, > 
“ASCII ‘MESSG* 
$$$LEN=.-SESMES 
*+FSECT FSCT 9 
MOV RO»- (SF) ; 
MOV #$$$MES ¥RO 9 
MOV Rl»~ (SF) 5 
MOV #$$$LENeR1 ; 
SAV.RO = 2 3 
SAV.RI = 0 , 
eIFF 


a 
9 
a 
¥ 


a> Se 


If arguments gre mot already in 
save them temrorarily on 


*NTYPE ADM.AL»MESSG 


Cr > “> Sr Gd 


IF NE sADM.AL 

MOV MESSGy~ (SF) 

SAV.RO = 0 9 
5 

SAV.R2 = 0 3 

*ENTC 

*¢NTYFE ADM.+A2*»LEN 3 

«IF NE vAIM.A2-1 ? 

MOV LEN»~ (SF) 3 
> 

SAV.RI = 0 ? 
y 


eLIF GErSAV.ROs 

’ 
SAV.R2 = 0 3 
*ENDC 


Swar the resisters with their 


stored on the stack. 
«IF EQsSAV.R2 3 
MOV R29- CSF) 5 


«LIF GE»SAV.RO»s 


ra 


y 


»IIF GEsSAV.RI1» 


4 


y 


*ENDIC 
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SAV.RO=SAV.ROt2 § 


SAV.RO=SAV.ROt2 § 


SAV.RI=SAV.RItF2 ¢ 


BRlank LEN ars means 
first form 

Set ur text in 
MSGTXT 


Fseact 


Rack to original Fsect 
Save old RO 

RO => messase 

Save old RI 

Ri = messade length 
Note RKO saved on stack. 
Note Ri saved om stack 


Second form of 
invocation 
the correct resistersys 


the stack 


Addressing mode of 
MESSG 

If anything but 

Save arsument or 
stack 

RO will be saved here 
later 

We'll meed to save R2 


"RO" 
the 


Addressing mode of LEN 
If anything but "Ri" 

Save arsument on the 
stack. 

Rl will be saved here 
later 

Increase 
offset of RO 

We'll need to save R2 


argument values which we 


If we need to save R2 
Save R2 

Increase 

of RO 
Increase 

of Ri 


offset 


offset 


104 
105 
106 
107 
108 
109 
110 
Lit 
Li2 
113 
L114 
115 
Lié 
Li? 
118 
Lig? 
L290 
121 
122 
12: 

124 


125 


IF 


MOV 
MOV 
MOV 
eENDC 


IF 

MOV 

MOV 

MOV 

eENDIC 
*ENTIC 


CALL. 


a 0 


GE »SAV.RO 


RO» R2 
SAV.ROCSP) » RO 


~R29SAV.ROCSP) 


GE eSAV.RI 
Ri»R2 


SAV.RICSF) rR1 
R2»SAV.RICSF) 


TYFOUT 


§ Restore resisters 
+TIF GE»sSAV.R2» MOV 
+ITIF GEvySAV.R1I» MOV 
+LIF GErSAV.RO» MOV 


eENDM 


TTPE 
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If RO’ 
stack. 
SWar 


Sr “Sr S> GP 


If Ri’ 


“i> “SP ‘ar “CD 


(SPO +t*R2 
(SFO +eR1 
(SP) +9RO 


stack. 
Swar Ril with its 
arsument value 


§ 
y 


ars was rut on 


RO with its 


b=) 


y 


argument value 


ars was rut on 


§ Forms of invocation 


Restore old R2 
Restore old Ri 
Restore old RO 


MCN DB OD Wh 


10 


“Ath “fp > Mth “Sh “Ch Sh “Ch RP “ED “EP “ED “Ee “EP “ED “OD “EP “Oh SP Gr “E> “Ee “SP “E> “E> “H> “Er “> S> “ar ar “SP “Ad “> sE> 


“MACRO INFUT BUFFER »LEN 
COPYRIGHT (C>} 1981 BY DIGITAL EQUIPMENT CORFORATION 


Macro to invoke the "TYFIN® routine to ineut data from 
TI?. 


Invoke usins? 
INFUT address, lensth 


where address and length sre the address amd 
lensth of the inreut buffer. 


QUTFUTS? Yetea is inreut synchronously from LUN § 
RO => buffer 


C-bit is set for errors clear for no 
error (for directive or I/0 errors) 


If mo errors Ri contains bete count from 
I/O stetus block. 


If a directive error is encounteredsy Ri 
is clears $0SW contains error code 


If an I/0 error is encountereds Ri 
contains error code from I/0 status block 


Needed subroutine module? TYFIN 


WARNINGS 3 1. ROUTINE USES EVENT FLAG #24 FOR 
SYNCHRONIZATION 
2e RO ANT Ri ARE DESTROYED 


+GLOBL TYFIN § Subroutine to issue QI0 
+ directive 
*¢ANTYPFE ADRMODIy BUFFER $¢$ Check addressing mode 


» LF NE y ADRMOL i Buffer rointer eglready in RO? 
MOV RUFFER»yRO § Nos move it there 

+ENDIC 
*NTYPE ADRMOUYLEN ¢§ Check addressing mode 

«IF NE» ADRMOD-1 § Length already in R1I? 
MOV LENyRi ¢ Noes move it there 


eENDC 


CALL TYFIN Call subroutine to issue QI0 
girective 


+ ENIIM 
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+TITLE TYFOUT Subroutine 
COPYRIGHT (C) 1981 BY DIGITAL EQ 


TYFOUT fe rovides a simele way for 
tyre out a messase on TIt. 


CALL. $ ISR FC» TYFOUT 
INFUTS 3 RO => ASCII or A 
Ri = O if strin 

= nO for AS 


LUN S is assumed +t 
QUTPUTS $ Messase is outreut 
All resisters eres 


C-hit is set for e 
error 


WARNING? Routine uses event 
synchronization 


The macro "TYPE" can be used to 
in a feirly transearent manner. 


“> “> “Gp “a> SP Mh Sh GP HP “Cd “Eh Er D> GP “Gd “SP “EP SP “Ge “E> “SS “> CSP “SD ED UP “HD 


*GLOBL LENGTH , 
3 
*MCALL QTOWSS 3 
; 
TYFOUT??$ TST Ri ; 
BNE 1% 9 
; 
CALL LENGTH > 
3 
1$3 MOV R29-CSF) 3 
SUB #49SF ’ 


MOY SFP ye R2 3 
> Tio @ garden variety outrut to TI 

QLIOWSS #IO.WVBy #5424. 99K 

RCC 2% r) 


“> 


AnT #49S5F 
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to outrut to TL: 
UIFMENT CORPORATION 


MACRO-1L1 routines to 


SCIZ message 
g is ASCIZ 
CII string of lensth m 


o he assigned to TI? 
sumchronously to LUN & 
erverd 


rrory clear for no 
flas #24 for 
invoke this routine 


Subroutine to determine 
length of string 
Sustem macro 


ASCII ineut or ASCIZ? 

Branch if ASCII. Ri 
already has lensth 

Find lensth of strings 
(returned in Ri) 

Save R2 on stack. 

Reserve srace for IOSE 

R2=3TOSEB 

¢ 

2eviROrsR1» #40> 

Branch om directive OK 


tirective error. Furse 
IO0SB from stack 


BR 
3 
§ [Tirective su 
’ bute counts 
3 
2éi CMF E 
BEQ 
SHI SEC 
BER 
A$ CLC 
S$? TST 
3 
> COMMON EXIT 
bss MOY 
RE TURN 
»ENTI 


&$ 


« 
9 


cceeeded. Record any 


Purse stack 


#IS.SUCs (SP) + 
4% 


(SPO +9R2 
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“Sr “Gr “CP “> GP SP Sh SP 


“S> “Sr 


Exit (with C-bit set) 


I/O errors: record 


I/0 error? 

Branch if mo error 

Set C-bit to indicate 
error 

Branch to get I/0 count 
Clear C-bit to indicate 
no error 

Clean ur stack 


Restore Re 
Return 


Sr MP Gh Sh Mk > Sh MIP “Ch SP CP > “> “SP “> Sem ASh “Hh “Wr “Gm “Ge “Se “> WP SER > “GP Cr WED We Ch “> “E> E> “Ch “GP 


a 


¥ 


“> 


e TITLE 


TYFIN Subroutine to inreut from TI? 


COPYRIGHT (C) 1981 BY DIGITAL EQUIPMENT CORPORATION 


TYFIN rrovides 


a simele way for MACKO-11 routines to 


inmeut data from Trt. 


CALL ¢ 


INFUTS 3 


OQUTFUTS ¢ 


WARNING? 


JSR FC» TYFIN 


RO => [neut buffer 
Ri Lensth of buffer in butes 


LUN 3S is assumed to be assigned to TI? 
Yate if inreut synchronously from LUN & 
RO is unchansed 


Cebit is set for errory cleasr for no 
error (for directive or I/0 errors) 


If ma errory RL contains byte count from 
I/O status block. 


If @ directive error 15 encountereds Ri 
is clears $25W contains error code 


If an I/0 error is emcountereds Ri 
contains error code from I/0 status 
Dlack 


ROUTINE USES EVENT FLAG #24 FOR 
SYNCHRONIZATION 


The macro "INPUT" can be used to invoke this routine 


in es feiris 


*MCALL 


TYPING = MOV 


SUB 
MOV 

Tlo @ sarden 
QLOWSS 
RCC 
ALT 


CLR 
SEC 
BR 


R2e~ (SF) 


tLransrarent manners 


QTOWsSs i System macro 


i Save R2 
£459 SF § Reserve srace for IOSE 
SF y RS § R2=2>TOSK 


variety ineut from TI? 


HIO.RVBRs #52 #2469 9R29 92 ROVR LS 


2h § Branch on directive ON 
#4°SF + [tirective error. Furse 
§ IOSE from stack 
Rt § Note directive error 
} 
&$ 5 exit 
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i > Re 


Sa! 


r 


GO Ni Gs 


3} Uirective succeeded. Check for I/0 errorsy record 
5 bete counts rurse stack 
3 


he MOV (SFI+4+sR1 > Get success/error code 
CMFE #IS.SUCsR1 ¢$ I/0 error? 
REQ 4s > EBrneh if mo error 
TST (SP )+ § Error. Forget about 
— I/O count 
SEC > Just return with C-bit 
> set and I/O status in 
5 Ri 
BR &$ > Branch to common exit 
4$3 CLC > Clear carry bit 
MOV (SFO+9R1 § Return IT/0 count in Ri 
¥ 
§ COMMON EXIT 
¥ 
&$2 MOV (SPO +9R2 ¢’ Restore K2 
RETURN § Return 
+END 


*TITLE LENGTH 
COFYRIGHT (C) 1981 BY DIGITAL EQUIPMENT CORPORATION 


LENGTH finds the length of an ASCIZ string 


CALL? CALL LENGTH 
INFUT? RO => ASCIZ string 
OUTFUT? RO r reserved 
Rio = Length of string (not including 


terminating mull) 


f “Re Sr E> Sh MP Wr SP Sh MP SP “EP “Sh “OP 


ENGTH?$ CLR Ri § Clear counter 
MOV RO»v- (SF) § Save rointer to 
> hedinning of strings 
1%3 TSTE (ROD + § Real character or mull 
+ byte? 
REQ 2s § Null means end of 
§ tring 
INC Ri + Count real character 
RR 1% ys And look at next byte 
obs MOV (SF) +eRO § Restore original 
§ FoOinter 
RETURN § Return 
«ENT 
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fab pet 
Me ON DH CFD Whe 


hs > 
?. 


“SP “EP EP Gh ED Gh “ED Ch MSP “EH Sh GP “GP Ce Wh SCP GH “WP “Gh > “E> “EP “a> “ED SP “ED “EP “> “o> > “> “ES “cr KP “Gr SS > “E> “Gm “> SEP “E> “> 


*MACRO DIRERR MESSAG»LENyFSCT 
COPYRIGHT (C) 1981 BY DIGITAL EQUIFMENT CORFORATION 


Macro to generate @ “directive error" message and 
Print out the value of the U0SWs felus a user-defined 
message. The task is forced to exit after the message 
is rrinted. 


The form of the resultant error messase is? 


QNIRECTIVE ERROR 
“USER-DEFINED MESSAGES 
NSW = “VALUES 


It is sussested that the user-defined message identify 
the oreration which returned the error, 


It is the caller’s resronsibility to check the c-bit 
erior to invoking DIRERR. This convention allows the 
user to eccert certain tyres of errorss then invoke 
QIRERR for any other kinds of errors. 


Invoke using one of two forms? 


VIRERRK <messase> 
or 
VIRERR ARDRESSsLENGTH 


In the first form vou srecify the text of the message. 
The macro reserves storase for the string. 


In the second form vou must use addressing modes toa 
srecify the address and length of 3 string which vou 
have reserved in your frosgram. The first arsdument is 
the address of am ASCII or ASCIZ string. The second 
arsument should have a value of 0 if the string is 
ASCIZ» else should he the lensth of the ASCII string. 


If vou use the first form and gre rrodgrammingd im other 
than the blank FPsects vou must exrelicitly rrovide 2 
mull Slen" arguments and surely as the third arsument 
the mame of the Psect to return to. 
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*GLOBL 
+GLOBL 


»GLOBL 


5 Offsets into 


a 
¥ 


«IF & 


$$$MES=,. 


$$$LEN=.~-S$$MES 


»GLORBL 
+GLOBL 
»GLOBL 


MOV 
LEN 


»PSECT 
*ASCIT 


»PSECT 


EREXIT 
NIRERT 


“a> “Gr “E> ‘er “ar 


ERARGS - 
ardument block? 
E.RUMA 

E. RUML. 

E.ROUSW 


S> a> “ar 


#ERARGS yR2 


S> a> “Se 


MSGTXT 
/MESSAG/ 
FSCT 


#$$$MES*E.RUMACR2) 
#$$$LENrE.RUML OR2) 


MESSAG»E.RUMACR2) 
LENyE.RUMLCR2) 


$USWeE.-RUSWCR2) ¢ 
#UTRERT»R3 3 
EREXIT 3 

) 
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Common routine 
"NIRECTIVE ERROR" 
ineut string for 
$E0MSG 

$E0NMSG arsument block 


User-messaese address 
User-messase length 
nsw value 


R2=>$E0MSG ars block 
Rlank len ars means 
first form 


3’ Load message addr 
s and message length 
§ into ars block 


¢ Load messade addr 
§ and messase length 
§ into ars block 


Load [UISW into ars block 
R3=>$E0IMSG ineut strings 
Jum to common error 
exit routine 


+ 


OT NID LEDS Glo 


> > Mb MP SP VP “Sh UD “Sh Ed SP “GP WP “> SD “E> “EP “D> “EP “ED SD “NP Gd “GP “EP “CD WED “> ser “ED “ER “EP “ED “HP ED “HP “E> SGP “SP “EP SP D> “C> “Ed > “E> “Er “SP “SP HD ED 


*+MACRO IOERR TOSB»MESSG»LEN»s PSCT 
COPYRIGHT (CC) 1981 BY DIGITAL EQUIPMENT CORPORATION 


Macro to generate an "I/0 error’ messade and rrint out 
the value of the I/O status blocks rlus a user-defined 
message. The task is forced to exit after the messade 
is printed. 


The form of the resultant error messase is? 


I/0 ERROR 
“user-defined messasde> 
I/O STATUS BLOCK = “hie syclb>/<2nd word> 


where “hb” and “*lib" gre the high byte and low byte of 
the first word of the I/0 status block. 


It is sussested that the user-defined message identify 
the oreration which returned the error, 


It is the caller’s resroansibility to check the first 
word of the I/0 status block rrior to invoking ITOERR: 
to see whether the oreration has heen &@ SUCcCCcCessS or @ 
failure. This convention agllows the user to eccert 
certain tyres of errorsy then invoke IOERR for any 
other kinds of errors. 


Invoke using one of two forms? 


TOERR losby<imessade> 
or 
TOERR ioshyaddresssylansth 


In either form “iosh" is the address of the I/0 status 
blocky in any addressing mode. 


In the first form you srecify the text of the message. 
The macro reserves storase for the strings. 


Im the second form you must use addressing modes to 
srecify the address and lensth of a string which you 
have reserved im your frogram. The second arsument is 
the address of am ASCII or ASCIZ string. The third 
argument should have a value of 0 if the string is 
ASCIZ»s else should he the length of the ASCII string. 


If vou use the first form and sre rrogramming im other 
than the blank Psects you must explicitly erovide 2 
mull "LEN" arsuments and surely es the fourth arsument 
the name of the Fsect to return to. 
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+GLOBL EREXIT + Common routine 
»-GLOBL IOERIN § "I/O ERRORS ineut 
§ string for $E0MSG 
+GLOBL ERARGS +s $E0MSG arsument block 
¢ Offsets into arsument block? 
+GLOBL E.RUMA + User-message address 
»>GLOBL E.RUML + User-messade lensth 
+GLOBL E.RIOS y First word of I/0 
ys status block 
bd 
MOV #ERARGS+R2 § R2=>$E0MSG ara block 
+-IF &B LEN § Blank LEN ars means 
y first form 
*+FSECT MSGTXT 
$$$MES=,. 
+ASCII /MESSG/ 
$$$LEN=.-$$6MES 
*FSECT FSCT 
MOV #¢$$$MES*SE.RUMACR2) ¢ Load message addr 
MOV #$$$LENeE.RUMLOR2) ¢ and message lensth 
; into ars block 
+ LFF 
MOV MESSG*sE.RUMACR2) + Load message addr 
MOV LENvyE.RUML (R2) 3; and messade lensth 
; y into ars block 
»ENDIC 
§ Cory I/0 status block into $ED0MSG ars block 
MOV IOSE+sR1i ys Ri => I/0 status block 
MOVE LORD RS > Get hi bute of first 
3 ’ word (Cand sism-extend 
; § it) 
MOV R3sE.RIOSCR2) § Cory into ars block 
MOVE CRideRS + Get lo byte and 
§ $isn-extend 
MOV R3vsE.RIOS+2¢°R2) ¢ Cory into ard block 
MOV 2CRLIIVE.RIOSt4(R2) ¢ Cory 2nd word of 
y IOSE 
MOV #IOERIN:R3 § RZ => S$EIIMNSG ineut 
y strings 
AMP EREXIT ¥ Jume to common error 
§ exit routine 
+ENDIIM 
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+MACRO FCSERR FIOBsMESSGyLEN»PSCT 
COFYRIGHT (C) 1981 BY DIGITAL EQUIFMENT CORPORATION 


Macro to generate an "FCS ERROR" message and erint out 
the error code erlus a user-defined message. The task 
is forced to exit after the message is rrinted. 


The form of the resultant error messade is? 


FCS ERROR 
USER-DEFINED MESSAGE> 
NSW = <VALUE? 


or 


FCS ERROR 
“USER-DEFINED MESSAGE> 
I/O ERROR CODE = <VALUE> 


It is sussested that the user-defined message identify 
the oreration which returned the error. 


It is the caller’s resronsibility to check F-ERR in 
the FIR erior to invoking FCSERR: to see whether the 
oreration has been a success or a failure. This 
convention allows the user to accert certain tyres of 
errorss then invoke FCSERR for any other kinds of 
errors. 


Invoke using one of two forms? 


FCSERR fdby»<message> 
or 
FCSERR fdibvaddressslensth 


Im either forms “"fdb" is the address of the file 
descrirtor block for the FCS oreration which hes 
generated the error. 


In the first form you srecify the text of the message. 
The macro reserves storage for the string. 


In the second form you must use addressing modes to 
srecify the address and length of a string which you 
have reserved in your Frogram. The second ardument is 
the address of am ASCII or ASCIZ string. The third 
argument should have @ value of 0 if the string is 
ASCIZ:» else should be the length of the ASCII string. 


If you use the first form and are rrogramming in other 
than the blank Fsects you must exrelicitly rrovide a 
null "len" arguments and surely as the fourth arsument 
the mame of the Psect to return to. 
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+GLOBL 
»GLOBL 
+GLOBL 
* Offsets into 
+GLOBL 
+ GLOBL 
+GLOBL 


“> “Se 


*MCALL 

FOOF $L. 
3 

MOV 
+IF B LEN 


*PSECT 
$$$MES=, 

»ASCIT 
$$$LEN=.-S$$MES 

+PSECT 

MOV 

MOV 


*ENTIC 
MOV 


MOVE 


MOV 
TSTE 


BEQ 
ys [Ttirective err 
MOV 
JMPF 
TO?3 MOV 
JMF 


+E NIM 


EREXIT 
FCSQRIR»FCSIO 
ERARGS 
arsgument block? 
E.RUMA 

E.RUML 

E.«RCOD 


FOOF $L. 


#ERARGS »R2 


MSGTXT 


/MESSG/ 
FSCT 


¥$$¢MES*E.RUMACR2 > 
¥$$¢$LEN2E.RUML CR2) 


MESSG»E.RUMACR2) 
LENE. RUML (R2) 
FOB sR 
FsERRCRI) » RO 


ROvE.RCOUCR2) 
F -ERR+1 (R121) 


Io 

or? 
#FCSDIRsRS 
EREXIT 
#FCSIOsRS 


EREXIT 
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S> S> “a> 


“Sr Gp “ap “Sr 


Sh > “E> “EP “CP > “Sh UD 


> Sr S> S> “E> “EP “> Sr 


Common routine 
$EUMSG inrut strings 
$EDMSG srsgument block 


User-messadge address 
User-messade lensth 
Error code (SW value 
or I/O error) 


lefine FUB offsets 


R2=:¢E0MSG ars block 
Blank len ers means 
first form 


+ Load message addr 
> and messase Lensth 
1 into ars block. 


$s Load message addr 
+; and messase lensth 
s into ars block 


Ri=> file descriretor 
block 

Get error code 
(sisgn-extend) and 
store into ars block 

Ttirective error or I/0 
error? 

BRranch om I/O error 


R3=> "FCS DIRECTIVE 
ERROR® $E0MSG string 
Jume to common error 
exit routine 
R3=>"FCS I/70 ERROR" 
$EDMSG string 

Jume to common error 
exit routine 


= 
~OOOwnN RC D> Gh 


et pt ee 
b& Wh 


~ 
Ch 


pa ea 
oo NT & 


P3 
> 


bh RS 
co NI & 


t 
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47 


vO 
od 
wa 


Or G> Se 


“Sr “> “> WP “Ce “Gr > “GP “EP “E> “E> “EP “GD Wr “HP WD “ae sce “SCP? “CD “E> 
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*TITLE EREXIT ERROR EXIT ROUTINE 
COPYRIGHT (C) 1981 BY DIGITAL EQUIPMENT CORPORATION 


This i8 8 common exit routine called by the 
error-rrocessing macros DTRERR, ITOERR: and FCSERR. It 
tures out an error message and forces the task to exit 
with status "severe error", 


Calli SMF EREXIT 


Ineuts? R2 => ERARGS C4E0MSG arsument block» 
defined in this routine) 


The arsumenmt block has already 
been filled in with the 
wuser-messase descrirtory and the 
system error code (IiSW value or 
IOSK eointer)d). A user-messasde 
length = 0 means that the 

user messacdce is im ASCIZ form. 


R3 => One of the EDMSG inreut strings 
defined in this routine 


*-GLOBL #E0MSG 
*GLOBL LENGTH Comeutes length of 
ASCIZ string 
System macro 


Surrlied macro 


*MCALL EXST$C 
*«MCALL TYPE 


S> E> a> “ED 


Error exit status 


“> 


EX$SEV = 4 


$EQMSG inreut strings? 


IRERT?? «ASCII /ZNDIRECTIVE ERROR/ 


eASCIT /SZNAVA/ 
*ASCIZ /ANTSW = “ALS 


FCSUIRS$ .ASCIIT /ANFCS ERROR/ 


a 


ASCII /SAZANZVA/ 
eASCIZ /ANTSW = ZL/ 


¥ 
IOERING $ .ASCII @“ZNI/0O ERRORG 


a 


sASCIT SANAVA/ 
*ASCIZ @ANI/O STATUS BLOCK = Atty “D0 / Zle@ 


FCSTO?$ .-ASCII @ANFCS ERROR@ 


“Sr “Gd 


eASCIT /ANZVA/ 
eASCIZ @ANI/O ERROR COLE = “ne 
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+ BLAKE 
+EVEN 
ersumen 


QUTRBUF ¢ 


> $E0MSG 

ERARGS 3 3 

i RUML==.-ERARGS 
»WORTD 

E.»«RUMA==,.-ERARGS 
+WORL 

* Error codes 

E-RUSW==,-ERARGS 

E«RIOS==,-ERARGS 

E.RCOD==,-ERARGS 
»WORT 
+WORT 
«WORT 

; 

EREXIT?3 
TST 


MOV 
MOV 
CALL 
TYPE 


EXST$C 
END 


200. 


t block 


E.».RUML CR2) 

1% 
E+«RUMACR2) » RO 
LENGTH 
RivsE.RUML CRS) 
#0UTBUF 9» RO 
R3sRi 

$E0MSG 
#QOUTRUF »R1 


EX#$SEV 
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er “er “SP 


“> “Gr “Er 


“Cr “> ‘Gh “Gh “> “> “EP “E> “E> “Gr “Gm “GP “a> ‘E> “Er EP “ED 


$EDMSG outeut buffer 


User-messase length 
User-messase address 


sw for OIRERR 
IOSEB for IOERR 
FCS code for FCSERR 


User message ASCII or 
ASCIZ? 

ASCII 

If ASCIZs find lensth 
RO => user messade 
Creturned in Rid 

Set length field in 
argument block 

Quteut buffer for 
$EIMSG 

Fut ineut string 
rointer into rrorer 
resister for #E0MSG 
(returns length im Ri> 

Tyre out formatted 
message 

Exit/severe error 


APPENDIX B 
CONVERSION TABLES 


Table B-1 Decimal/Octal, Word/Byte/Block Conversions 


Words(18)/Words(8) Bytes(1@)/Bytes (8) Blocks (19) /Blocks (8) 


l/l 2/2 

32/40 64/188 : 1/1 

1K =1924/2009 2848/4080 . 32/49 
2K =2048/4998 4896/1600 64/108 
4K =4896/190908 8192/28888 128/280 
8K =8192/290098 16384/486008 256/408 
16K =16384/400080 32768/1 88800 512/180 
32K =32768/1900000 65536/2090980 1924/2880 
64K =65536/29008008 | 131872/498099 . 2048/4006 
128K=131072/490000 262144/1 980000 4996/1800 


Table B-2 APR/Virtual Addresses/Words Conversions 


APR Virtual Addresses Words 
) GBOSOH-G17776 G-4K 
1 : G20800-037776 4-8K 
2 G40008-857776 | 8-12k 
3 868968-877776 12-16K 
4 188980-117776 16-20K 
5 129800-137776 20-24K 
6 149808-157776 24-28K 
7 160980-177776 28-32K 
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‘APPENDIX C 
FORTRAN/MACRO-11 INTERFACE 


CALLING A MACRO-11 SUBROUTINE FROM A FORTRAN PROGRAM 
FORTRAN Program Call: 

CALL SUBNAM (I,J,K) 
MACRO translation: 


1. Set up table of arguments. 


Yeon 
aacass of + | 


2. Issue subroutine call. 


R5 ----> 


JSR PC,SUBNAM 
or 
CALL SUBNAM 


The FORTRAN Callable MACRO-11 Subroutine 


; Accessing: 

: Argument count = (R5) 
: Argl = @2(R5) 

: Arg2 = @4(R5) 

: Arg3 = @6(R5) 

SUBNAM: : . 


RTS PC ; or RETURN 


oy Be) 


CALLING A FORTRAN PROGRAM FROM A MACRO-11 PROGRAM 


In the MACRO program: 


LINK: - BYTE 
-WORD 
-WORD 
«WORD 
A: - WORD 
Bs - WORD 
C: -WORD 


QwnQd WY w 


MOV #LINK,R5 
JSR PC,SUB 


In the FORTRAN program: 


SUBROUTINE SUB (L,M,N) 
N=L+M 

RETURN 

END 


NOTE 
This method is also used to call a FORTRAN 
callable subroutine (written in MACRO-1l1). 


Example 7-3 in the Static Regions module -shows a 


shareable 


library LIB.MAC, which contains FORTRAN callable subroutines. 
USELIB.MAC, also in Example 7-3, shows a_ referencing task which 


calls subroutines in the library. 
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APPENDIX D 
PRIVILEGED TASKS 


RSX-11M systems have two classes of tasks, privileged and 
nonprivileged. The basic difference is that privileged tasks have 
certain system-access capabilities that nonprivileged tasks do not 
have. These privileges include one or more of the following: 


e Access to Executive routines and data structures 
e Automatic mapping to the I/O page 
e Bypass of system security features. 


NOTE 
Privileged tasks may be hazardous to a = run- 
ning system. 


Use one of the following qualifiers (switches) to build a 
privileged task. 


1. /PRIVILEGE:8 qualifier (MCR /PR:@) 


This task is built in the same way as a nonprivileged task 
and does not map to the Executive or the I/O page. It 
can, however, do the following: 


e Bypass file protection 


e Issue directives which require privileges (e.g., Alter 
Priority, QIO for Write Logical Break-through) 


e Issue QIOs to write logical blocks to a mounted 
volume, regardless of who issued the MOUNT or ALLOCATE 
command. 


2. /PRIVILEGE:4 or /PRIVILEGE:5 (MCR /PR:4 or /PR:5) 


This task has the privileges of a /PRIVILEGE:@ task, plus 
it maps to the Executive and the I/O page. The user task 
code is mapped beginning at APR 4 or 5, as specified. The 
APRS below the one specified are used to map to the 
Executive, and APR 7 is used to map ,the I/O page. Use 
/PRIVILEGE:4 if the Executive is 16K words or less; use 
/PRIVILEGE:5 if the Executive is between 16K and 20K 
words. If the task code extends beyond the end of the 
addresses mapped by APR 6, then APR 7 is used to map_ the 
excess code, and the task does not map to the I/0 page. 
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Privileged tasks are discussed in detail in the RSX-11M 
Internals Course. See also Chapter 6 on Privileged Tasks in the 
RSX-11M/M-PLUS Task Builder Manual. 
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APPENDIX E 
TASK BUILDER USE OF PSECT ATTRIBUTES 


The Task Builder collects scattered occurrences of program 
sections of the same name and combines them in a single area in 
your task image. The program section attributes control how the 
Task Builder collects and places each program section. 


See Chapter 2 of the RSX-11M/M-PLUS Task Builder Manual for a 
complete discussion of program section attributes. 


Example of allocation code attributes: 
CON (concatenate) versus OVR (overlay) 
1. A.OBJ has Psect Q,CON - length 1800(198) words 
B.OBJ has Psect Q,CON - length 5@(19%) words 
When task-built: 
LINK A,B 


Yields 15@(1@) words in Psect Q 
(first A's 100(18@) words, then B's 58(18) words). 


2. A.OBJ has Psect Q,OVR - length 199(198) words 
B.OBJ has Psect Q,OVR - length 5@(19) words 
When task-built: 

LINK A,B 
Yields 100(190) words in Psect Q 


(A's 108(18@) words. B's 5@(1@) words are the 
same as A's first 5@(1@) words). 


519 


Example of scope code attributes: 


LCL (local) versus GBL (global) 


Overlay Tree B.ODL file: 
Bl B2 -ROOT B-*! (B1,B2-B3) 


a aan . END 


Task-build command (for all): LINK B/OVERLAY DESCRIPTION 


l. 


B.OBJ has Psect Q,LCL,CON - length 199(198) words 
B1.0BJ has Psect Q,LCL,CON - length 58(18) words 
When task-built: 


Yields 188(18@) words in Psect Q in root segment B 
Yields 58(18) words in Psect Q in overlay segment Bl 


B.OBJ has Psect Q,GBL,CON - length 198(18) words 

B1.0BJ has Psect Q,GBL,CON - length 5@(18) words 

When task-built: 

yields 158(18) words in Psect Q in root segment B (in the 
segment closest to the root); B's 100(18) words, then 
Bl's 5@(1@) words. . 
If GBL,OVR instead, yields 180(18@) words in Psect Q in the 


root segment. B's 188 words, with Bl's 58@(18@) words the 
same as B's first 58@(18) words. 
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3. B2.O0BJ has Psect Q (LCL or GBL) - length 190(18) words 
B3.OBJ has Psect Q (LCL or GBL) - length 58(19) words 
When task-built: 

If CON, yields 1580(18) words in Psect Q in overlay segment 


B2 (allocation collected, since it is all in the same 
overlay segment). 


If OVR instead, 108(18) words in Psect Q in overlay 
segment B2. B3's 5@(18) words are the same as B2's first 
5@(18) words. 


LCL and GBL are used only for overlaid tasks. In a 
non-overlaid task or within an overlay segment in an overlaid 
task, allocations are collected when either LCL or GBL is 
specified, as in Example 3. 

Example of FORTRAN COMMONs at Psects: 
Psect attributes are always: RW,D,GBL,OVR,REL 

COMMON /RDATA/ 1(188) 


Macro translation: 


-PSECT RDATA,RW,D,GBL,OVR,REL 
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APPENDIX F 
ADDITIONAL SHARED REGION TOPICS 


SHARED REGIONS WITH OVERLAYS 


e Can be referenced using a smaller window in referencing 
task 


e Reuse virtual addresses in the referencing task 
e Must be memory-resident overlays 


e Have overlay structures which are placed in the .STB file 
and later placed in root segment of referencing task. 


BUILDING A RESIDENT LIBRARY WITH OVERLAYS 
1. Code and assemble library modules. 
2. Write regular .ODL file to define overlay structure. 
e Typical structure has a null root. 
3. Task-build as a shared region. 


e Only symbols defined or referenced in the root are 
included in the .STB file. 


e Force inclusion of global references into root, when 
necessary, using GLBREF option. 


Example .ODL file OVRLIB.ODL (Figure F-1): 


. NAME OVRLIB 
- ROOT OVRLIB-*! (H, I-J) 
~ END 


Example task-build command: . 


>LINK/NOHEADER/MAP/SYMBOL TABLE/OPTIONS OVRLIB/OVERLAY- 
->_ DESCRIPTION a 

Option? STACK=@ 

Option? PAR=OVRLIB: 140600: 40000 

Option? GBLREF=H,1,J 

Option? <RET> 
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Referencing task is created using regular procedure to 
reference library OVRLIB. 


See section 5.1.4 (on Shared Regions with Memory-Resident 
Overlays) in the RSX-11M/M PLUS Task Builder Manual for additional 


information. 
PHYSICAL 
MEMORY 


VIRTUAL 
MEMORY eee 


160000 APR7 
140000 APR6 | 
120000 APRS 
100000 APR4 
60000 APR3 
40000 APR2 


20000 APR 1 


0 APRO 


TK-7773 


Figure F-1 A Shared Region With Memory-Resident Overlays 
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REFERENCING MULTIPLE REGIONS IN A TASK 


e Use the usual procedure if: 


- The number of available APRs in the referencing task 
is sufficient 


- Shared regions are logically independent (one library 
does not call the other library) 


e If shared regions are built absolute, APRs (and virtual 
addresses) cannot overlap. 


Example task-build for logically independent libraries (Figure 
F-2): 


Libraries: ARES built absolute at V.A. 160000(8); length 4K 
, words 
BRES built absolute at V.A. 120000(8); length 6K 
words 


Referencing task: REF 
>LINK/MAP/OPTIONS REF 
Option? RESLIB=ARES/RO 


Option? RESLIB=BRES/RO 
Option? <RET> 
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/ 
/ 
/ 
/ 
VIRTUAL / / 
MEMORY oe of 
/ 
TASK REF / / 


160000 APR? : 
140000 APR6 
‘Sian APR5 i 
100000 APR4 | 
60000 APR3 
40000 APR2 
20000 APR1 


0 APRO 


Figure F-2 


a 


PHYSICAL 
MEMORY 


Referencing Two Resident Libraries 
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INTERLIBRARY CALLS 
One library can call another library 
FORRES calls FCSRES 


To build libraries with interlibrary calls, use any of these 
techniques. 


e Build as a single combined ADEE Ys then build referencing 
task (Figure F-3). 


e If referenced library does not contain overlays (Figure 
F-4): 


- Build referenced library. 


- Build referencing library, specifying referenced 
library to resolve calls. 


- Build referencing task, specifying only referencing 
library. 


e If referenced library has overlays (Figures F-5 and F-6): 


- You must revector interlibrary calls to allow access 
to overlay structure and autoload vectors (always in 
root of referencing task). 


- Once revectoring is included, build shared regions and 
referencing task as if regions are logically 
independent. 


Example task-build commands for each technique follow. 


Example task-build command for combined libraries (Figure 
F=-3): 


>LINK/MAP/NOHEADER/SHAREABLE: LIBRARY/SYMBOL_ TABLE- 
->/OPTIONS F4PRES,LB:[1,1]F4POTS/LIBRARY 

Option? STACK=@ 

Option? PAR=F4PRES: 120000: 69008 

Option? <RET> 


Referencing task is created using normal procedure to 
reference the library F4PRES. 
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PHYSICAL 
MEMORY 


VIRTUAL wa 


a F4PRES 
MEMORY 
- (FCSRES) 


160000 APR7 FAPRES 


' (FCSRES) 
12K WORDS 


140000 APR6 


120000 APR5t 


100000 APR4 § 


60000 APR3 


40000 APR2 


USER 


20000 APR1 (12K WORDS) 


0 APRO 


TK-7776 


Figure F-3 Referencing Combined Libraries 


528 


Example task-build commands for building one library, then 
building the second (referencing) library (Figure F-4): 


>LINK/MAP/NOHEADER/SHAREABLE: LIBRARY/SYMBOL TABLE- 
->/OPTIONS/CODE: PIC FCSRES -_ 
Option? STACK=@ 

Option? PAR=FCSRES: 0: 20000 

Option? <RET> 


>LINK/MAP/NOHEADER/SHAREABLE: LIBRARY/SYMBOL TABLE- 
->/OPTIONS F4PRES,LB:[1,1]F4POTS/LIBRARY 
Option? STACK=9 

Option? LIBR=FCSRES:RO 

Option? PAR=F4PRES: 149000: 40000 

Option? <RET> 


Referencing task is created using normal procedure to 
reference just the library F4PRES. F4PRES must be mapped using 
APRs 6 and 7 because it is built absolute. FCSRES is mapped at 
the next available APR, namely APR 5, because it is built position 
independent. 
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160000 


140000 


120000 


100000 


60000 


40000 


20000 


APR 


APR 


APR 


APR 


APR 


APR 


APR 


APR 


PHYSICAL 
MEMORY 


F4PRES 


VIRTUAL ee 
MEMORY Pe 


7 F4PRES 
(8K WORDS) 

6 

E seo: 2 
5 E seo: 2 WORDS) 

7 FCSRES . 

4 
3 | LL 
2 

USER 
1 (12K WORDS) 
(0) 


TK-7771 


Figure F-4 Building One Library, Then Building 


a Referencing Library 
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FCS1 FCS2 FA4PCLS USER 


JMPTBL:: 


AUTOLOAD ROUTINE, MAPS TO 
FCS1, THEN TRANSFERS CONTROL 


TK+-7777 


Figure F-5 Revectoring 


See Section 5.2.1.3 (on User Task Vectors Indirectly Resolve 
all Interlibrary References) in the RSX-11M/M-PLUS Task 
Builder Manual for additional information on _  revectoring. See 


also Section 5.2.3 on Examples for commented task-build commands 
for building libraries with revectoring. 


531 


Example task-build commands when revectoring are used 


(Figure 


F-6): 


>LINK/MAP/NOHEADER/SHAREABLE: LIBRARY/SYMBOL TABLE- 


->/OPTIONS/CODE: PIC FCSRES/OVERLAY DESCRIPTION 


Option? 
Option? 
Option? 
Option? 
Option? 


Option? 
Option? 


STACK=9 


PAR=FCSRES: @: 20000 


GBLREF= 
GBLREF= 
GBLREF= 


GBLREF= 
<RET> 


~ CLOSE 


sCSI1 


«CSI2 


~WAIT 


>LINK/MAP/NOHEADER/SHAREABLE: LIBRARY/SYMBOL TABLE: -— 
->F4PCLS/TASK:F4PCLS/OPTIONS F4PRES,LB:[1,1]F4POTS- 
~>/LIBRARY, LB: [1,1]SYSLIB/INCLUDE: FCSVEC 


Option? 
Option? 
Option? 
Option? 
Option? 
Option? 


Option? 
Option? 


Referencing 
reference libraries FCSRES and F4PCLS. 


STACK=9 


PAR=F4PCLS: 140000: 499009 


GBLINC= 
GBLXCL= 
GBLXCL= 
GBLXCL= 


GBLXCL= 
<RET> 


~FCSJT 
- CLOSE 
-CSI1 
-CSI2 


-WAIT 


task is 


created using normal 
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procedure 


to 


PHYSICAL 
MEMORY 


F4PCLS 


FCS2 
FCS1 


TK-7775 


VIRTUAL oe 
MEMORY ae 


F4PCLS 
(8K WORDS) 


160000 APR7 


140000 APR6 


| Fest FCS2 
120000 APRs [| (4K WORDS) | (4K WORDS) 


40000 APR2 


USER 


20000 APR1 (12K WORDS) 


0 APRO 


Figure F-6 Using Revectoring When Referencing Library Has Overlays 


CLUSTER LIBRARIES 


Task 


e Allow shared libraries to overlay each other (Figure F-7). 


- Can use one window for several libraries. 


- Only enough virtual address space is needed 
largest library. 


@e One library can call another. 
- Generally moving in one direction only. 


- First library in cluster is initially mapped 
autoload). 


- When a call is made to another library in cluster: 


Autoload routines save mapping context and 
called library for a call. 


Original library is remapped for return 
subroutine. 


for 


(no 


map 


from 


e Revectoring is necessary for interlibrary calls (Figure 


PoSjs 


- Special coding must be included in the resident 


libraries. 


e Some special rules must be followed when building 
resident libraries. 


the 


e Are useful for FORTRAN tasks using the resident object 
time system (FORRES, F4PRES, or F77RES), plus layered 


products. 


See Section 5.2 on Cluster Libraries in the RSX-11M/M-PLUS 


Builder Manual for additional information. 

Example of task-build command: 
>LINK/MAP/OPTIONS/CODE:FPP CLSDEM,LB:[1,1]HLLFOR,- 
->LB:[1,1]F4POTS/LB,LB:[1,1]FDVLIB/LB 


Option? CLSTR=F4PCLS,FMSCLS,FCSRES:RO 
Option? <RET> 
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Figure F-7 Cluster Libraries (Sheet 2 of 2) 
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APPENDIX G 
ADDITIONAL EXAMPLES 


The following examples should be available on-line, probably 
under UFD [2@2,1]. They are needed for the Tests/Exercises. 
Therefore, they are listed here in case -they are not available 
on-line at your site. 


I *TITLE REATIF 

2 eIQNENT 7/017 

3 *ENABL LC § Enable lower case 

4 + 

5 § File READF.MAC 

& ; , 

? § This task starts urs sets event flas ls reads the 

3 * event flass:s moves them into resisters RO-R3S and then 
9 § exits, It uses the $ form of the directive calls. 

10 3 

11 + The fless ere returned as follows? 

12 ; 

13 ; word O = event flads 1-16 
14 ; word 1 = event flass 17-32 

13 # word 2 = event flags 33-48 

16 ? word 3 = event flasds 49-64 

17 ; bit set means fled is sety 

18 3 bit clear means flas is clear 

19 Lee 
20 
ei *+MCALL ROAFSsSETFSesEXIT&#SoDIRG §¢ Sustem macros 
9°9 
23 BUFF + BLAW 4 ’ Buffer for event flas 
24 y Velues 
25 READY RAF $ BUFF , DFR for Read Al] Event . 
2d § Flass directive 
27 
28 SETF? SETFS 1 + DPR for Set Event Flas 
29 § directive 

30 

41 START? CLA R4 * Clear error counter 
32 NIRS ESETF > Set event fled 1 
33 BCS ERR > Branch om dir error 
34 iks #REATL * Read the event flass 
35 § (1 - 64). 

36 RCS ERR2 * Branch om dir error 
37 MOV BUFF s RO § Move the event flag 
38 MOV BUFF +2 9R1 * velues into the 

39 MOV BUFF +4 2R2 y Tesisters 

40 MOV RUFF +é9h3 

41 IoT $ Trar and disrelay 

42 y YTesisters 

43 

44 § Come here on directive errors 

435 ERR2 ¢ INC R4 ¢ R4=2 for read error 
46 ERR1 3 INC R4 § R4=] for set event 
47 + fles error 
43 MOV $OSWyRO § Error code into RO 
49 IoT i Trar and disrelay the 
30 y resisters 
Si +ENT START 


Example G-1 Reading the Event Flags (for Exercise 1-1) 
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WHROWONR Ubon. 


‘St> “> “> Sr “SP “E> “M> Ee “D> “ED 


fat pe be pe 


2d 3 


25° TYPEL 
26 TYPE?! 
27 TYPES! 
28 «TYFE4! 
29 ERR 


31 ERR 


33 ERRS? 


41. VATA: 
42 NEL TXT? 
43 TYTXT? 
44 NOTXT$ 


43 CRLKY 


where 


+TITLE CSI 
+ITHENT /01/7 
+ENABL LC : § Enable lower case 


CSI illustrates the use of the cammand string 
interrreter. This task accerts ae command line from the 
terminal in the form? 


devilxyygI filename.filetyreiversion/switen 


Switen can he} 
TE - Telete file 
QIIN - Dliselay N cories of file 


*MCALL GCMLES sGCML Ss CST $eCSTéi vy CST ga 

*MCALL CST#$SVsCSTS$SWeCSTENT 

*MCALL FSRSZ$e FOU BOF $y FURCHAy POOR GAs FINITS 
*MCALL QTOWSS sy QIOWS sDIRGsEXITSS 

*MCALL DELET#$ 2s OP ENGR» OPENGWs GETS» PUTS es CLOSES 


*NLIST BEX 
LOCAL DATA 


QIOWs TO.WVBySyleoeeKERRI ey STZ1 40> 
QIlOWS IO.WVBy Syle vy eS ERRS 9ST Z29 40> 
QLOWS TO.WVERy Sede so eS ERR Sy SITZ3 940% 
QlOWSs TO.WVUBR: So ly ee ySERR4y STZ4% 40> 
-ASCII /GET COMMAND LINE ERRORS 
SIZi=.-ERRL 

-ASCII /CSI ERROR. ILLEGAL COMMANT/ 
SIZ2=.-ERR2 

*ASCIT /CSI ERROR. FILE SPEC ERROR 
SIZ3=,-ERRS 

~ASCIT ERROR FERFORMING TASK 
SIZ4=.-ERR4 

BLAKE 100. § Quteut text buffer 
+ BLAKE 132. § Transfer tuffer 
*ASCIZ /YOU HAVE REQUESTED A Z7A JOBS 
+EVEN 

*+WORT O y Arsument block. 
*ASCITI /NELETE/“O% § ASCIL text 
ASCII /STYPES LOE SO> O02 

*ASCII /NOTHING/Z 

+ EVEN 


fiefine CSI offsets 
allocate CSI storase 


CSTs 
+ BLAB C.SIZE 
EVEN 


c> “> 


Yelete mask. 
Visrelas mask 


DEMSK = 
UIMSK 


Hot 
hoe 
“ey “Gr 


Example G-2 Using the Routines GCML and CSI (for Exercise 19-6) 
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a4 SWTRL? § Switch descrirtor table 
55 CSI$SW NE»sNEMSK 3 telete switeh = TE 

36 CST#SW DOLesDIMSKy»»sy»NUM § Tliselay switch = Dts 

57 § also allow DTIN 

38 CSI#N0 § End of switch table 

9 


&0 CST$SV 


&3 COTLSNT 


OCTAL »COFY »29NUM$ 


; 
a 
3 
a 
3 
a4 
3 


Value N for /OLIN is 
im octal and will 
be stored in CORY 

End of switch value 
table 


4é *GET COMMANT LINE BLOCK DEFINITIONS 


&8 FSRSZ$ 
70 GELS GCMLES 
72 PVE ¢ FOBIIF $ 
74 FORCEA 


76 FOOFP SA 


7? ¢ NOTE! Need 2 


81 «EVEN 


83 JMF TEL: «WORT 


1 


gCSTy 9S 


yTRUFF yy 132. 


LyCBLAEC SNS 


2nd FOB 


NONE sQELETE sOITSFLY 


* 
y 


Sr “Ah "RY "Re MY “RP “HS “SD 


disrlaw 


GCML uses record T/0 


Fromet with “CSl’ on 
LUN & 

FIER for file to delete 
or disrlauw. 

URE AT TRUFFs lLensth 
132, 

LUN ly dataset 

deserietor from CSit 


a 


¢ Jum table for 


84 i Subroutines derendins 
85 3 on switches 

B84 

97 CORY? +WORT ¢) § Value for Nin /TL3N 


88 «ENABLE 


90 START? FINITS 


95 NEXT? GCML 
96 BCC 

97 § Check for “Z. 
98 CMF 
99 BNE 

100 EXIT$S 
101 REALER? DIRS 


103 EXIT#S 


LSE 


#GBLIN 
10% 
If “Zy 


#GE EOF sGRLK+G.ERR 


REALZER 


ETYPEL 


a 
# 
a 
? 
a 
y 
s 
¥ 
a 
¥ 
a 
? 
a 
¥ 


a 


S> “> Se “Sd “C: 


Initiaalize FCS», this 

is normally done with 
an OFEN statement. 

For delete we do nat 
need an oren statement. 
Fromet and get command 
Rranch if command OK 


¢ Is it “Z? 
Rranch on other error 
Exit 
liselay error text for 
get command line error 
Exit 


1605 * Parse inreut for illegal cheracters 


107 LO? CSI¢i 


TCBLK ys GRLK+G.-CMLO+2»GRLK+G.CMLID § Format 


108 + is CSI addry addr of 
109 ; commands Lensth of 
1106 § command 


Example G-2 Using the Routines GCML and CSI (for Exercise 16-6) 
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Example G-2 


BCC 
DIRS © 


20% 
TYPE 


EXIT#S 
i Create ae dataset 


2O8S CST #2 


RCC 
QIRG 


30% 
ETYFES 


EXIT#&S 


* Cell the arrrorriate 


JOBS MOV FF TIE » RO 
MOV CRLAE+C.MRWI oR 
ASL. Ri 


CALL @JMF TEL CRD) 
BR NEXT 
NONE » 


§ Subroutine entered 


NONE ¢ MOV #NOTXT sUATA 


* Cammon disrlayw messase code 
QOUTM: MOV 
MOV 
MOV 
CALL. 
QTOWSS 
RETURN 


FRUFF eo RO 

HEMT eo RL 

KATA R2 

$ETIMSG 
ETOWV Bo RS etd yoy 


’ Subroutine TIELETE ~ 


QELETE? MOV HOEL TXT » DATA 


BR QUTM 


descriretor Prom 


“A> “S> “Sy > “Mb “SY “SP 


if no 


Branch on OK command 

Uiselay error text for 
illegal command 

Exit 


“Se “RY RY “OD 


the file srecification 


TCBLA YQUTFUT 9 ASWTBL ¢ Exreet outeut file 


$F eC 
Branch on 
Nigelay text 

grec error 
Exit 


file srec ON 
for file 


Seo Wh “ID “Se 


subroutine 


Address of file 
desaorietor 

Mask value = Ov ly aor 2 

Youble for word affset 
imto Jdume table 

Call the subroutine 

Get next command line 


Switches srecified 


Satour for outeuk of 


MESSedke 


“a> “Moh 


Setour for #EOMSG 


“Ee “Sr “Oo “Se 


Egat messede 
eR BUPRPF 9 Ry bas ¢ 
Return 


Kisrley 


< 


"S> 


Just diselay a messase 


Setour for outeut of 
MEeSseste 

Branch to commor 

§ diselay code 


Se “tr “SD 


§ Subroutine OQISPLY - Gust disrelay a messase 


QISPLY: MOV ETYTXT VATA 


BR QUT 


eENT START 


Routines GCML 
(Sheet 3 of 


Using the 
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§ Setour for outeut of 
$ MmMmessacse 

§ Branch to common 

§ disrelay cade 


and CSI (for Exercise 
3) 


19-6) 


APPENDIX H 
LEARNING ACTIVITY ANSWER SHEET 


Learning Activity 2-1 (Directives) 


l. 


Fither: a) Do some work, then check the flag by using the 
CLEFS 35. directive. Check the DSW. IS.SET (=+2) means 
the flag was set; IS.CLR (=@) means the flag was clear, 
or b) read flags 4 through 64 using RDAFS and then test 
bit 2 of the third word in the buffer to read flag 35. In 
either case, keep doing more specific work and 
periodically check the flag. 


The Executive, would only set event flag 1 for Task A. It 
would not set Task B's event flag 1; therefore, Task B 
wouldn't realize that the data had been sent. 


Local flags are accessible only to the task itself. They 


are specifically provided for synchronization between the 
Executive and a task. : 
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Learning Activity 6-1 (Overlays) 
ee 
. ROOT-*! (P,Q) 
. END 


2. LINK/MAP ROOT,P,Q 


Learning Activity 6-2 
1. Diagram 


JOB] JOB XX 


(2. ROOT MAIN-TOTAL-* (A-(JOB1,JOBXX) ,B) 
. END 


3. «ROOT MAIN-TOTAL-—*! (A-! (JOB1,J0BXxX) ,B) 
» END ‘ 


4. ..ROOT MAIN-TOTAL-*! (A-(JOB1,JOBXX) ,B) 
- END 
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Learning Activity 10-1 (File Control Services) 
Without a User Record buffer (no spanning of blocks): 


FDBDFS 

FDRCSA FD. PLC 

FDOPSA 1, DFNB 
DFNB: NMBLKS YOURS , MAC 


Use locate mode 
Use LUN 1, default name block 
File Spec 


™e te NO 


With a User Record Buffer 


FDBDFS 
FDRCSA FD.PLC,URB,8@.; 8@.= maximum record size, 
Record size can be checked after 


the file is opened as well. 


=e te SMO 


FDOPSA 1,DFNB 
DFNB: NMBLKS YOURS.MAC 


You can use a dataset descriptor as well. 
If you use a default name block to specify TI:, use: 


NMBLKS ,,,TI,@ 
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GLOSSARY 


ASYNCHRONOUS SYSTEM TRAP (AST) - A system condition which occurs 
as a result of a specified event such as completion of an I/O 


request. 


On occurrence of the event, control passes to an AST _ Service 
routine, and the AST is added to an Executive first-in first-out 
queue for the task in which the service routine appears. 


ATTACH - Device: Dedicate a physical device unit for exclusive 
use by the task that requested attachment. 


A task attaches a given device by issuing a QIO directive, or QIO 
and WAIT directive, specifying the I/O function IO.ATT. 


Region: Include a region in a task's logical address space. 


A task attaches a region by isSuing an Attach Region directive or 
by being the target of another task's Send-By-Reference directive. 


CLUSTER LIBRARIES - A special setup with shared resident libraries 
which permits a task to use the same virtual address window to map 
several difficult libraries. For example, the resident FORTRAN 
Object Time System and the resident FCS library could use the same 
virtual addresses. The run-time routines map and remap the 
regions as they are needed, somewhat similar to what happens with 
regular memory-resident overlays. 


DATASET DESCRIPTOR - A six-word area in the user task containing 
sizes and addresses of ASCII data strings, which FCS consults in 
order to obtain a run-time file specification. 


A dataset descriptor for a given file is a user-created data 
structure which contains a file specification for that file. 


When the filename block associated with a given file does not 
contain sufficient information to enable FCS to do run-time file 
processing on that file, FCS tries to get the needed information 
from the file's dataset descriptor, if specified. Otherwise, FCS 
consults the file's default filename block, if specified, in order 
to get the desired information. 


DEFAULT FILENAME BLOCK —- An area in the uSer task that supplies 
FCS with those default values that are needed to build a routine 
file specification. 


When the filename block associated with a given file does not 
contain sufficient information to allow FCS to process the file, 
and when a dataset descriptor does not contain the needed 
information, then FCS consults the default filename block 
associated with the file to obtain the missing information. 
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GLOSSARY 


A default filename block may be used to supply a default name, 
extension, and/or version for the file. The MACRO programmer uses 
the NMBLKS macro to create this block at assembly time. 


DETACH - Device: Free an attached physical device unit for use by 
tasks other than the one that attached it. 


A physical device unit can only be detached by means of an I0.DET 
I/O function issued by the task that attached it, or by the 
Executive, if the task is terminated with the device still 
attached. 


Region: Remove a region from a task's logical address space. 


A task detaches a region by issuing a Detach Region directive or 
by exiting. 


DIRECTIVE STATUS WORD - A word in the user task header into which 


the Executive returns status information about the most recently 
called directive. 


After processing a directive, the Executive passes the status of 
that directive to the issuing task by putting a success or error 
code into the task's Directive Status Word, which is assigned the 
global label SDSW. If $DSW is negative, the Executive rejected 
the directive; if SDSW is +1, the directive was successful. 


EVENT FLAG - A software flag which can be specified in a program 
request to indicate to the issuing task which of several specified 
events has occurred, 


There are 96(1@) event flags. 


Event flags 1 - 32(10@) are local 
33(10) - 64(1@) are system global flags 
65(10) - 96(1@) are group global flags 


Local flags are used for intra-task synchronization, while group 
global and system global flags are used for inter-task 
synchronization and communication. 


EXECUTIVE DIRECTIVE - A program request for Executive services. 

An Executive directive is issued from a FORTRAN program by calling 
a subroutine in the system object library. It is issued from a 
MACRO-11 program by invoking a macro in the system macro library. 
FILE DESCRIPTOR BLOCK (FDB) - The tabular data structure which 


provides FCS with information needed to perform I/O operations on 
a file. 
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A task must allocate, through calls to the FDBDFS macro, or 
dynamically through the use of run-time macros. 


FILE STORAGE REGION (FSR) - The area in user task which FCS- uses 
to buffer all virtual blocks read or written during record 
processing. 


FCS requires one FSR block buffer for each file to be opened at 
the same time for record I/O. When the task requests a record 
that is not in the FSR buffer, FCS reads a virtual block from the 
file into the task's file storage region. On the other hand, FCS 
writes virtual blocks in the file storage region to the file when 
a record must be put to the file. 


The user task allocates this area by issuing an FSRSZS$ macro. 


FILENAME BLOCK — The part of a file's File Descriptor Block which 
FCS uses for building, and later using, a file specification. 


The filename block contains the file's UFD, name, extension, 
version number, device name, and unit. When a file is initially 
opened, FCS fills in the filename block from user-Supplied 
information in the dataset descriptor and/or default filename 
block. 


I/O STATUS BLOCK - A two-integer array which receives success or 
error codeS on completion of an I/O request. If an I/O status 
block has been specified in an I/O request, the Executive clears 
both words when the I/0 operation is queued. On completion, the 
low byte of the first word contains +1 if the I/O was’ successful, 
and a negative error code otherwise. 


If the I/O function involved a transfer, the second word contains, 
on completion, the number of bytes transferred. 


LOGICAL ADDRESS SPACE - The set of all physical addresses to which 
a task has access rights. 


If a task is running on a mapped system that includes support for 
the memory management directives, it may issue directives in order 
to manipulate its logical address space at run time. 


LOGICAL BLOCK - A 512(1@) byte (256(1@) word) block of data on a 
block addresSable volume. 


To achieve device independence, each block addressable volume is 
organized into logical blocks, numbered g to n-1, where n is the 
number of logical blocks on the volume. 


The mapping of logical blocks to physical blocks is handled by the 
driver. . 
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LOGICAL UNIT NUMBER (LUN) - A number associated with a physical 
device unit during a task's I/O operations. 


The association of a LUN in a task with a given physical device 
may be done by the Task Builder, by the operator using the 
REASSIGN command, or at run time by the task, by issuing an Assign 
LUN directive. 


RANDOM ACCESS - A method of I/O to disk files in which records (or 
virtual blocks) are specified by record (or virtual block) number. 


Under FCS, a file must be organized into fixed length records in 
order for a task to do random access to the file. 


FCS supports the use of block I/O, in which virtual blocks are 
read from, or written to, the file without regard for the 
Structure of those blocks. The FORTRAN language does not support 
block I/O. 


READ/WRITE MODE —- An FCS file access method in which the uSer task 
uses the READS and WRITES macros to do block-structured I/O to a 
file. 


REGION —- An area consisting of one or more contiguous 32.-word 
blocks of physical memory. 


A region may be named or unnamed, but is always assigned a unique 
region ID. A region has an associated protection word which 
specifies the access rights a task may have with respect to that 
region. Any task that satisfies the region protection word may 
attach a named region, but no task can attach an unnamed region 
unless the task has the region ID. 


RESIDENT COMMON - A shared region which contains data. 


RESIDENT LIBRARY - A shared region containing subroutines’ and/or 
functions. 


SEQUENTIAL ACCESS -— A mode of record access in which the n+l1th 
record in the file is processed after the nth record in the file. 


Each record is assigned a record number, and each successive GET 
or PUT causes the record number to be incremented. 


SYNCHRONOUS SYSTEM TRAP (SST) - A “software interrupt" which 
typically occurs as a result of an error or fault within the 
executing task. 


On recognition of an SST, the Executive aborts the task, unless 
there is an SST vector table to an SST routine in the task. 
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VIRTUAL ADDRESS - A 16-bit address which may be directly specified 
uSing one of the general purpose registers. 


A task specifies a virtual address whenever it uses one of the 
addressing modes in executing an instruction. Up to 32K virtual 
word addresses may be specified by a task. 


On a mapped system, the memory management hardware dynamically 
maps virtual addresses to real physical addresses. 


VIRTUAL ADDRESS WINDOW - A contiguous chunk of a task's. virtual 
address space, 


Each virtual address window in a task begins on a 4K word boundary 
and consists of one or more 32(18@) word blocks of virtual address 
space. Each window has a unique number assigned to it by the 
Executive. Window @ always maps the task's header, stack, and 
code. A task may divide its virtual address space into eight 
windows. 


VIRTUAL BLOCK — One of the logical blocks belonging to a file. 


Each file consists of one or more logical blocks. The logical 
blocks belonging to a file are called virtual blocks 1, 2, 3, etc. 
The mapping of virtual blocks in a file to logical blocks on disk 
is performed by the file system. 


WINDOW DESCRIPTOR BLOCK (WDB) - A data structure used in a task in 
order to represent a dynamically created window. 


Doi. 


